@@ -2,6 +2,17 @@ Revision history for CHI
** denotes an incompatible change
+0.41 Mar 1, 2011
+
+* Improvements
+ - Add RawMemory driver, a faster version of Memory that does not serialize/deserialize
+ values
+ - Add etc/bench/bench.pl for benchmarking CHI and non-CHI caches
+ - Publish current benchmarking results in CHI::Benchmarks
+
+* Testing
+ - Stop using test counts (http://stackoverflow.com/questions/690342/)
+
0.40 Feb 27, 2011
* Improvements
@@ -5,7 +5,24 @@ MANIFEST
META.json
META.yml
Makefile.PL
+etc/bench/bench.pl
+htdocs/CHI.html
+htdocs/CHI/Benchmarks.html
+htdocs/CHI/CacheObject.html
+htdocs/CHI/Constants.html
+htdocs/CHI/Driver.html
+htdocs/CHI/Driver/Base/CacheContainer.html
+htdocs/CHI/Driver/CacheCache.html
+htdocs/CHI/Driver/Development.html
+htdocs/CHI/Driver/FastMmap.html
+htdocs/CHI/Driver/File.html
+htdocs/CHI/Driver/Memory.html
+htdocs/CHI/Driver/Metacache.html
+htdocs/CHI/Driver/Null.html
+htdocs/CHI/Driver/RawMemory.html
+htdocs/CHI/Stats.html
lib/CHI.pm
+lib/CHI/Benchmarks.pod
lib/CHI/CacheObject.pm
lib/CHI/Constants.pm
lib/CHI/Driver.pm
@@ -17,6 +34,7 @@ lib/CHI/Driver/File.pm
lib/CHI/Driver/Memory.pm
lib/CHI/Driver/Metacache.pm
lib/CHI/Driver/Null.pm
+lib/CHI/Driver/RawMemory.pm
lib/CHI/Driver/Role/HasSubcaches.pm
lib/CHI/Driver/Role/IsSizeAware.pm
lib/CHI/Driver/Role/IsSubcache.pm
@@ -42,6 +60,7 @@ lib/CHI/t/Driver/File.pm
lib/CHI/t/Driver/File/DepthZero.pm
lib/CHI/t/Driver/Memory.pm
lib/CHI/t/Driver/NonMoose.pm
+lib/CHI/t/Driver/RawMemory.pm
lib/CHI/t/Driver/Subcache.pm
lib/CHI/t/Driver/Subcache/l1_cache.pm
lib/CHI/t/Driver/Subcache/mirror_cache.pm
@@ -58,6 +77,7 @@ t/00-load.t
t/Bugs.t
t/Constants.t
t/Driver-Memory.t
+t/Driver-RawMemory.t
t/GetError.t
t/Initialize.t
t/Sanity.t
@@ -72,6 +72,6 @@
"web" : "https://github.com/jonswar/perl-chi"
}
},
- "version" : "0.40"
+ "version" : "0.41"
}
@@ -45,4 +45,4 @@ requires:
resources:
bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
repository: git://github.com/jonswar/perl-chi.git
-version: 0.40
+version: 0.41
@@ -44,7 +44,7 @@ my %WriteMakefileArgs = (
'Time::Duration::Parse' => '0.03',
'Try::Tiny' => '0.05'
},
- 'VERSION' => '0.40',
+ 'VERSION' => '0.41',
'test' => {
'TESTS' => 't/*.t'
}
@@ -2,7 +2,7 @@ NAME
CHI - Unified cache handling interface
VERSION
- version 0.40
+ version 0.41
SYNOPSIS
use CHI;
@@ -10,6 +10,7 @@ SYNOPSIS
# Choose a standard driver
#
my $cache = CHI->new( driver => 'Memory', global => 1 );
+ my $cache = CHI->new( driver => 'RawMemory', global => 1 );
my $cache = CHI->new( driver => 'File',
root_dir => '/path/to/root'
);
@@ -17,7 +18,7 @@ SYNOPSIS
root_dir => '/path/to/root',
cache_size => '1k'
);
- my $cache = CHI->new( driver => 'Memcached',
+ my $cache = CHI->new( driver => 'Memcached::libmemcached',
servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
l1_cache => { driver => 'FastMmap', root_dir => '/path/to/root' }
);
@@ -30,15 +31,18 @@ SYNOPSIS
# Create your own driver
#
- my $cache = CHI->new( driver_class => 'My::Special::Driver' );
+ my $cache = CHI->new( driver_class => 'My::Special::Driver', ... );
- # Basic cache operations
+ # Cache operations
#
my $customer = $cache->get($name);
if ( !defined $customer ) {
$customer = get_customer_from_db($name);
$cache->set( $name, $customer, "10 minutes" );
}
+ my $customer2 = $cache->compute($name2, "10 minutes", sub {
+ get_customer_from_db($name2)
+ });
$cache->remove($name);
DESCRIPTION
@@ -74,6 +78,9 @@ AVAILABILITY OF DRIVERS
* CHI::Driver::Memory - In-process memory based cache
+ * CHI::Driver::RawMemory - In-process memory based cache that stores
+ references directly instead of deep-copying
+
* CHI::Driver::File - File-based cache using one file per entry in a
multi-level directory structure
@@ -95,6 +102,8 @@ AVAILABILITY OF DRIVERS
* CHI::Driver::BerkeleyDB - Cache in BerkeleyDB files
+ * CHI::Driver::Redis - Cache in Redis
+
This list is likely incomplete. A complete set of drivers can be found
on CPAN by searching for "CHI::Driver".
@@ -0,0 +1,352 @@
+#!/usr/bin/perl
+#
+# Compare various cache backends
+#
+use Cache::Benchmark;
+use Cwd qw(realpath);
+use Data::Dump qw(dump);
+use DBI;
+use DBD::mysql;
+use File::Basename;
+use File::Path;
+use Getopt::Long;
+use Hash::MoreUtils qw(slice_def);
+use List::Util qw(sum);
+use List::MoreUtils qw(uniq);
+use Pod::Usage;
+use Text::Table;
+use Try::Tiny;
+use YAML::Any qw(DumpFile);
+use warnings;
+use strict;
+
+my %cache_generators = cache_generators();
+
+sub usage {
+ pod2usage( -verbose => 1, -exitval => "NOEXIT" );
+ print "Valid drivers: " . join( ", ", sort keys(%cache_generators) ) . "\n";
+ print "To install all requirements:\n cpanm " . join(" ", sort(uniq(map { @{$_->{req} || []} } values(%cache_generators)))) . "\n";
+ exit(1);
+}
+
+my $count = 10000;
+my $set_frequency = 0.05;
+my ( $complex, $drivers_pattern, $help, $incs, $sort_by_name );
+usage() if !@ARGV;
+GetOptions(
+ 'c|count=i' => \$count,
+ 'h|help' => \$help,
+ 'n' => \$sort_by_name,
+ 's|set_frequency=s' => \$set_frequency,
+ 'd|drivers=s' => \$drivers_pattern,
+ 'x|complex' => \$complex,
+) or usage();
+usage() if $help || !$drivers_pattern;
+
+my $value =
+ $complex
+ ? { map { ( $_, scalar( $_ x 100 ) ) } qw(a b c d e) }
+ : scalar( 'x' x 500 );
+my $sets = int( $count * $set_frequency );
+my $iterations = 10;
+
+require CHI;
+
+print "benchmarking $count operations split over $iterations iterations\n";
+print "CHI version $CHI::VERSION\n" if $CHI::VERSION;
+
+my $cwd = dirname(realpath($0));
+my $data = "$cwd/data";
+rmtree($data);
+mkpath( $data, 0, 0775 );
+
+my %common_chi_opts = ( on_get_error => 'die', on_set_error => 'die' );
+
+my %caches;
+foreach my $name (grep { /$drivers_pattern/ } keys(%cache_generators)) {
+ try {
+ if (my $req = $cache_generators{$name}->{req}) {
+ Class::MOP::load_class($_) foreach @$req;
+ }
+ $caches{$name} = $cache_generators{$name}->{code}->($count);
+ } catch {
+ warn "error initializing '$name', will skip - $_";
+ }
+}
+my @names = sort(keys(%caches));
+print "Drivers: " . join( ", ", @names ) . "\n";
+
+my $cb = new Cache::Benchmark();
+$cb->init( keys => int($sets / $iterations), access_counter => int($count / $iterations), value => $value );
+
+my %results;
+foreach my $iter (0..$iterations-1) {
+ print "Iteration $iter\n";
+ foreach my $name (@names) {
+ my $cache = $caches{$name};
+ add_fake_purge($cache);
+ $cb->run($cache);
+ foreach my $field qw(get_time set_time reads writes runtime) {
+ $results{$name}->{$field} += $cb->get_raw_result->{$field};
+ }
+ }
+}
+
+my (%colvalues, $reads, $writes);
+foreach my $name (@names) {
+ my $generator = $cache_generators{$name};
+ my $result = $results{$name};
+ my @colvalues = (
+ $name,
+ sprintf( "%.2fms", $result->{get_time} * 1000 / $result->{reads} ),
+ sprintf( "%.2fms", $result->{set_time} * 1000 / $result->{writes} ),
+ sprintf( "%.2fs", $result->{runtime} ),
+ $generator->{desc},
+ );
+ $colvalues{$name} = \@colvalues;
+ $reads = $result->{reads};
+ $writes = $result->{writes};
+}
+
+my $tb = Text::Table->new( 'Cache', "Get time\n&right", "Set time\n&right", "Run time\n&right", 'Description' );
+my $sort_field = $sort_by_name ? 0 : 3;
+my @rows =
+ sort { $colvalues{$a}->[$sort_field] cmp $colvalues{$b}->[$sort_field] }
+ keys(%colvalues);
+$tb->add( @{ $colvalues{$_} } ) for @rows;
+
+printf ("%s gets, %s sets, %s total operations\n", $reads, $writes, $reads+$writes);
+
+print $tb;
+DumpFile( 'results.dat', \%colvalues );
+
+sub add_fake_purge {
+ my ($cache) = @_;
+ if (!$cache->can('purge')) {
+ my $method_name = ref($cache) . "::purge";
+ no strict 'refs';
+ *$method_name = sub {};
+ }
+}
+
+sub cache_generators {
+ return (
+ cache_cache_file => {
+ req => ['Cache::FileCache'],
+ desc => 'Cache::FileCache',
+ code => sub {
+ Cache::FileCache->new(
+ {
+ cache_root => "$data/cachecache/file",
+ cache_depth => 2,
+ }
+ );
+ }
+ },
+ cache_cache_memory => {
+ req => ['Cache::MemoryCache'],
+ desc => 'Cache::MemoryCache',
+ code => sub {
+ Cache::MemoryCache->new();
+ }
+ },
+ cache_fastmmap => {
+ req => ['Cache::FastMmap'],
+ desc => 'Cache::FastMmap',
+ code => sub {
+
+ my $fastmmap_file = "$data/fastmmap.fm";
+ Cache::FastMmap->new( share_file => $fastmmap_file, );
+ }
+ },
+ cache_memcached_lib => {
+ req => ['Cache::Memcached::libmemcached'],
+ desc => 'Cache::Memcached::libmemcached',
+ code => sub {
+ Cache::Memcached::libmemcached->new(
+ { servers => ["localhost:11211"] }, );
+ }
+ },
+ cache_memcached_fast => {
+ req => ['Cache::Memcached::Fast'],
+ desc => 'Cache::Memcached::Fast',
+ code => sub {
+ Cache::Memcached::Fast->new( { servers => ["localhost:11211"] } );
+ }
+ },
+ cache_memcached_std => {
+ req => ['Cache::Memcached'],
+ desc => 'Cache::Memcached',
+ code => sub {
+ Cache::Memcached->new( { servers => ["localhost:11211"] } );
+ }
+ },
+ cache_ref => {
+ req => ['Cache::Ref::CART'],
+ desc => 'Cache::Ref',
+ code => sub {
+ my $count = shift;
+
+ Cache::Ref::CART->new( size => $count * 2 );
+ }
+ },
+ chi_berkeleydb => {
+ req => ['CHI::Driver::BerkeleyDB'],
+ desc => 'CHI::Driver::BerkeleyDB',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'BerkeleyDB',
+ root_dir => "$data/chi/berkeleydb",
+ );
+ }
+ },
+ chi_dbi_mysql => {
+ req => ['CHI::Driver::DBI', 'DBD::mysql'],
+ desc => 'CHI::Driver::DBI (mysql)',
+ code => sub {
+ my $mysql_dbh =
+ DBI->connect( "DBI:mysql:database=chibench;host=localhost",
+ "chibench", "chibench" );
+ CHI->new(
+ %common_chi_opts,
+ driver => 'DBI',
+ dbh => $mysql_dbh,
+ create_table => 1,
+ );
+ }
+ },
+ chi_dbi_sqlite => {
+ req => ['CHI::Driver::DBI', 'DBD::SQLite'],
+ desc => 'CHI::Driver::DBI (sqlite)',
+ code => sub {
+ my $sqlite_dbh =
+ DBI->connect( "DBI:SQLite:dbname=$data/sqlite.db",
+ "chibench", "chibench" );
+ CHI->new(
+ %common_chi_opts,
+ driver => 'DBI',
+ dbh => $sqlite_dbh,
+ create_table => 1,
+ );
+ }
+ },
+ chi_fastmmap => {
+ desc => 'CHI::Driver::FastMmap',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'FastMmap',
+ root_dir => "$data/chi/fastmmap",
+ );
+ }
+ },
+ chi_file => {
+ desc => 'CHI::Driver::File',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'File',
+ root_dir => "$data/chi/file",
+ depth => 2
+ );
+ }
+ },
+ chi_memcached_fast => {
+ req => ['CHI::Driver::Memcached::Fast'],
+ desc => 'CHI::Driver::Memcached::Fast',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'Memcached::Fast',
+ servers => ["localhost:11211"],
+ );
+ }
+ },
+ chi_memcached_lib => {
+ req => ['CHI::Driver::Memcached::libmemcached'],
+ desc => 'CHI::Driver::Memcached::libmemcached',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'Memcached::libmemcached',
+ servers => ["localhost:11211"],
+ );
+ }
+ },
+ chi_memcached_std => {
+ req => ['CHI::Driver::Memcached'],
+ desc => 'CHI::Driver::Memcached',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'Memcached',
+ servers => ["localhost:11211"],
+ );
+ }
+ },
+ chi_memory => {
+ desc => 'CHI::Driver::Memory',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'Memory',
+ datastore => {},
+ );
+ }
+ },
+ chi_memory_raw => {
+ desc => 'CHI::Driver::MemoryRaw',
+ code => sub {
+ CHI->new(
+ %common_chi_opts,
+ driver => 'RawMemory',
+ datastore => {},
+ );
+ },
+ },
+ );
+}
+
+__END__
+
+=head1 NAME
+
+bench.pl -- Benchmark cache modules against each other
+
+=head1 DESCRIPTION
+
+Uses Cache::Benchmark to compare a variety of CHI and non-CHI caches in terms
+of raw reading and writing speed. Sorts results by read performance. Does not
+attempt to test discard policies.
+
+=head1 SYNOPSIS
+
+bench.pl -d driver_regex [options]
+
+=head1 OPTIONS
+
+ -d driver_regex Run drivers matching this regex (required) - use '.' for all
+ -c count Run this many iterations (default 10000)
+ -n Sort results by name instead of by read performance
+ -s set_frequency Run this many sets as a percentage of gets (default 0.05)
+ -x|--complex Use a complex data structure instead of a scalar
+
+=head1 REQUIREMENTS
+
+=over
+
+=item *
+
+For the mysql drivers, run this as mysql root:
+
+ create database chibench;
+ grant all privileges on chibench.* to 'chibench'@'localhost' identified by 'chibench';
+
+=item *
+
+For the memcached drivers, you'll need to start memcached on the default port (11211).
+
+=back
+
+=cut
@@ -0,0 +1,72 @@
+<html><head><title>CHI::Benchmarks</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Benchmarks - Benchmarks of CHI and non-CHI drivers</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>These benchmarks were created with the script <code>etc/bench/bench.pl</code> in this distribution.</p>
+
+<p>For each cache: 9510 gets,
+490 sets,
+10000 total operations.</p>
+
+<p>OS X v10.6.6,
+2.2 GHz Intel Core 2 Duo,
+Perl 5.12.2.</p>
+
+<pre> Cache Get time Set time Run time Description
+ cache_ref 0.01ms 0.01ms 0.09s L<Cache::Ref>
+ chi_memory_raw 0.02ms 0.04ms 0.19s CHI::Driver::MemoryRaw
+ cache_fastmmap 0.02ms 0.05ms 0.23s Cache::FastMmap
+ chi_memory 0.04ms 0.07ms 0.42s CHI::Driver::Memory
+ chi_berkeleydb 0.05ms 0.13ms 0.53s CHI::Driver::BerkeleyDB
+ chi_fastmmap 0.06ms 0.09ms 0.59s CHI::Driver::FastMmap
+ cache_cache_memory 0.07ms 0.08ms 0.69s Cache::MemoryCache
+ cache_memcached_fast 0.09ms 0.13ms 0.91s Cache::Memcached::Fast
+ cache_memcached_lib 0.10ms 0.13ms 1.02s Cache::Memcached::libmemcached
+ chi_memcached_lib 0.14ms 0.19ms 1.44s CHI::Driver::Memcached::libmemcached
+ chi_memcached_fast 0.15ms 0.20ms 1.49s CHI::Driver::Memcached::Fast
+ chi_file 0.14ms 0.81ms 1.73s CHI::Driver::File
+ chi_dbi_sqlite 0.13ms 1.62ms 1.99s CHI::Driver::DBI (sqlite)
+ chi_dbi_mysql 0.22ms 0.28ms 2.20s CHI::Driver::DBI (mysql)
+ cache_memcached_std 0.24ms 0.19ms 2.34s Cache::Memcached
+ chi_memcached_std 0.28ms 0.25ms 2.78s CHI::Driver::Memcached
+ cache_cache_file 0.46ms 1.35ms 5.05s Cache::FileCache</pre>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,111 @@
+<html><head><title>CHI::CacheObject</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::CacheObject - Contains information about cache entries</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> my $object = $cache->get_object($key);
+
+ my $key = $object->key();
+ my $value = $object->value();
+ my $expires_at = $object->expires_at();
+ my $created_at = $object->created_at();
+
+ if ($object->is_expired()) { ... }</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>The <a href="http://search.cpan.org/perldoc?get_object" class="podlinkpod"
+>CHI</a> method returns this object if the key exists. The object will be returned even if the entry has expired, as long as it has not been removed.</p>
+
+<p>There is currently no public API for creating one of these objects directly.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="METHODS"
+>METHODS</a></h1>
+
+<p>All methods are read-only. The get_* methods are provided for backward compatibility with Cache::Cache's Cache::Object.</p>
+
+<dl>
+<dt><a name="key"
+>key</a></dt>
+
+<dd>
+<p>The key.</p>
+
+<dt><a name="value"
+>value</a></dt>
+
+<dd>
+<p>The value.</p>
+
+<dt><a name="expires_at"
+>expires_at</a></dt>
+
+<dd>
+<dt><a name="get_expires_at"
+>get_expires_at</a></dt>
+
+<dd>
+<p>Epoch time at which item expires.</p>
+
+<dt><a name="created_at"
+>created_at</a></dt>
+
+<dd>
+<dt><a name="get_created_at"
+>get_created_at</a></dt>
+
+<dd>
+<p>Epoch time at which item was last written to.</p>
+
+<dt><a name="is_expired"
+>is_expired</a></dt>
+
+<dd>
+<p>Returns boolean indicating whether item has expired. This may be probabilistically determined if an <a href="#expires_variance" class="podlinkpod"
+>"expires_variance"</a> was used.</p>
+</dd>
+</dl>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,45 @@
+<html><head><title>CHI::Constants</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Constants - Internal constants</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>These are constants for internal CHI use.</p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,46 @@
+<html><head><title>CHI::Driver::Base::CacheContainer</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:12 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::Base::CacheContainer - Caches that delegate to a contained cache</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>Role for CHI drivers with an internal '_contained_cache' slot that itself adheres to the Cache::Cache API,
+partially or completely.</p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,81 @@
+<html><head><title>CHI::Driver::CacheCache</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#CONSTRUCTOR_OPTIONS'>CONSTRUCTOR OPTIONS</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::CacheCache - CHI wrapper for Cache::Cache</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> use CHI;
+
+ my $cache = CHI->new(
+ driver => 'CacheCache',
+ cc_class => 'Cache::FileCache',
+ cc_options => { cache_root => '/path/to/cache/root' },
+ );</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This driver wraps any Cache::Cache cache.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="CONSTRUCTOR_OPTIONS"
+>CONSTRUCTOR OPTIONS</a></h1>
+
+<p>When using this driver, the following options can be passed to CHI->new() in addition to the <a href="http://search.cpan.org/perldoc?general%20constructor%20options#constructor" class="podlinkpod"
+>CHI</a>.</p>
+
+<dl>
+<dt><a name="cc_class"
+>cc_class</a></dt>
+
+<dd>
+<p>Name of Cache::Cache class to create, e.g. Cache::FileCache. Required.</p>
+
+<dt><a name="cc_options"
+>cc_options</a></dt>
+
+<dd>
+<p>Hashref of options to pass to Cache::Cache constructor. Required.</p>
+</dd>
+</dl>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,340 @@
+<html><head><title>CHI::Driver::Development</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#NAMING'>NAMING</a>
+ <li class='indexItem indexItem1'><a href='#MOOSE'>MOOSE</a>
+ <li class='indexItem indexItem1'><a href='#NAMESPACE'>NAMESPACE</a>
+ <li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
+ <ul class='indexList indexList2'>
+ <li class='indexItem indexItem2'><a href='#Required_methods'>Required methods</a>
+ <li class='indexItem indexItem2'><a href='#Overridable_methods'>Overridable methods</a>
+ <li class='indexItem indexItem2'><a href='#Optional_methods'>Optional methods</a>
+ </ul>
+ <li class='indexItem indexItem1'><a href='#DISCARD_POLICIES'>DISCARD POLICIES</a>
+ <li class='indexItem indexItem1'><a href='#TESTING'>TESTING</a>
+ <li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
+ <li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
+ <li class='indexItem indexItem1'><a href='#COPYRIGHT_%26_LICENSE'>COPYRIGHT & LICENSE</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::Development -- Manual for developing new CHI drivers</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> package CHI::Driver::MyDriver;
+ use Moose;
+ use strict;
+ use warnings;
+
+ extends 'CHI::Driver';
+
+ has ...;
+
+ __PACKAGE__->meta->make_immutable();
+
+ sub fetch {
+ my ( $self, $key ) = @_;
+
+ }
+
+ sub store {
+ my ( $self, $key, $data ) = @_;
+
+ }
+
+ sub remove {
+ my ( $self, $key ) = @_;
+
+ }
+
+ sub clear {
+ my ($self) = @_;
+
+ }
+
+ sub get_keys {
+ my ($self) = @_;
+
+ }
+
+ sub get_namespaces {
+ my ($self) = @_;
+
+ }</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This document describes how to implement a new CHI driver.</p>
+
+<p>The easiest way to start is to look at existing drivers, such as <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AMemory" class="podlinkpod"
+>CHI::Driver::Memory</a> and <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AFastMmap" class="podlinkpod"
+>CHI::Driver::FastMmap</a>.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAMING"
+>NAMING</a></h1>
+
+<p>If you are going to publicly release your driver, call it 'CHI::Driver::<i>something</i>' so that users can create it with</p>
+
+<pre> CHI->new(driver => 'I<something>');</pre>
+
+<p>If it's an internal driver, you can call it whatever you like and create it like</p>
+
+<pre> CHI->new(driver_class => 'My::Internal::CHI::Driver');</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="MOOSE"
+>MOOSE</a></h1>
+
+<p>CHI driver classes must be <a href="http://search.cpan.org/perldoc?Moose" class="podlinkpod"
+>Moose</a> based to be fully functional, since we use Moose roles to implement various features. For backward compatibility, non-Moose drivers will still work at a basic level, but you will see an error if using any feature requiring a role.</p>
+
+<p>All drivers must directly or indirectly extend <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver" class="podlinkpod"
+>CHI::Driver</a>.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAMESPACE"
+>NAMESPACE</a></h1>
+
+<p>All cache handles have an assigned namespace that you can access with <code>$self->namespace</code>. You should use the namespace to partition your data store. That is, two cache objects with different namespaces should be able to access the same key without any collision.</p>
+
+<p>Examples:</p>
+
+<ul>
+<li>The Memory driver uses a separate sub-hash inside its main memory hash for each namespace.</li>
+
+<li>The File driver uses a separate top-level directory for each namespace.</li>
+
+<li>The FastMmap driver uses a separate Cache::FastMmap file for each namespace.</li>
+</ul>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="METHODS"
+>METHODS</a></h1>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Required_methods"
+>Required methods</a></h2>
+
+<p>The following methods have no default implementation, and MUST be defined by your subclass:</p>
+
+<dl>
+<dt><a name="store_(_$self,_$key,_$data,_$expires_at,_$options_)"
+>store ( $self, $key, $data, $expires_at, $options )</a></dt>
+
+<dd>
+<p>Associate <i>$data</i> with <i>$key</i> in the namespace, overwriting any existing entry. Called by <a href="#set" class="podlinkpod"
+>"set"</a>. <i>$data</i> will contain any necessary metadata, including expiration options, so you can just store it as a single block.</p>
+
+<p>The <i>$expires_at</i> epoch value is provided in case you are working with an existing cache implementation (like memcached) that also has an interest in storing the expiration time for its own purposes. Normally, you can ignore this.</p>
+
+<p><$options> contains the hash of options passed to <a href="#set" class="podlinkpod"
+>"set"</a>, in case you want to implement driver-specific set options. Normally, you can ignore this.</p>
+
+<dt><a name="fetch_(_$self,_$key_)"
+>fetch ( $self, $key )</a></dt>
+
+<dd>
+<p>Returns the data associated with <i>$key</i> in the namespace. Called by <a href="#get" class="podlinkpod"
+>"get"</a>. The main CHI::Driver superclass will take care of extracting out metadata like expiration options and determining if the value has expired.</p>
+
+<dt><a name="remove_(_$self,_$key_)"
+>remove ( $self, $key )</a></dt>
+
+<dd>
+<p>Remove the data associated with the <i>$key</i> in the namespace.</p>
+
+<dt><a name="clear_(_$self_)"
+>clear ( $self )</a></dt>
+
+<dd>
+<p>Remove all data associated with the namespace. (Technically not required, but the default implementation, which iterates over all keys and calls <a href="#remove" class="podlinkpod"
+>"remove"</a> for each, is very inefficient).</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Overridable_methods"
+>Overridable methods</a></h2>
+
+<p>The following methods have a default implementation, but MAY be overriden by your subclass:</p>
+
+<dl>
+<dt><a name="BUILD_(_$self,_$options_)"
+>BUILD ( $self, $options )</a></dt>
+
+<dd>
+<p>Define the Moose BUILD method if you want to process any options specific to your driver.</p>
+
+<dt><a name="fetch_multi_hashref_(_$keys_)"
+>fetch_multi_hashref ( $keys )</a></dt>
+
+<dd>
+<p>Override this if you want to efficiently process multiple fetches. Return a hash reference from keys to fetched data. If a key is not available, it may be left out of the hash or paired with undef. The default method will iterate over <i>$keys</i> and call fetch for each.</p>
+
+<p>This method is called by <a href="http://search.cpan.org/perldoc?get_multi_arrayref" class="podlinkpod"
+>get_multi_arrayref</a> and <a href="http://search.cpan.org/perldoc?get_multi_hashref" class="podlinkpod"
+>get_multi_hashref</a>.</p>
+
+<dt><a name="store_multi_(_$key_data,_$options_)"
+>store_multi ( $key_data, $options )</a></dt>
+
+<dd>
+<p>Override this if you want to efficiently process multiple stores. <i>$key_data</i> is a hash of keys and data that should be stored. The default will iterate over <i>$key_data</i> and call store for each pair.</p>
+
+<p>This method is called by <a href="http://search.cpan.org/perldoc?set_multi" class="podlinkpod"
+>set_multi</a>.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Optional_methods"
+>Optional methods</a></h2>
+
+<p>The following methods have no default implementation, and MAY be defined by your subclass, but are not required for basic cache operations.</p>
+
+<dl>
+<dt><a name="get_keys_(_$self_)"
+>get_keys ( $self )</a></dt>
+
+<dd>
+<p>Return all keys in the namespace. It is acceptable to either include or omit expired keys.</p>
+
+<dt><a name="get_namespaces_(_$self_)"
+>get_namespaces ( $self )</a></dt>
+
+<dd>
+<p>Return namespaces associated with the cache. It is acceptable to either include or omit namespaces with no valid keys.</p>
+</dd>
+</dl>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DISCARD_POLICIES"
+>DISCARD POLICIES</a></h1>
+
+<p>You can create new discard policies for <a href="http://search.cpan.org/perldoc?size%20aware" class="podlinkpod"
+>CHI/SIZE AWARENESS</a> caches, to choose items to discard when the cache gets full. For example, the Memory driver implements an LRU policy.</p>
+
+<p>To implement a discard policy <i>foo</i>, define a subroutine <i>discard_policy_foo</i>, which takes a driver object and returns a closure that returns one key each time it is called. The closure should maintain state so that each key is only returned once.</p>
+
+<p>For example, here's the Memory driver's LRU implementation. It utilizes a hash containing the last used time for each key.</p>
+
+<pre> sub discard_policy_lru {
+ my ($self) = @_;
+
+ my $last_used_time = $self->{metadata_for_namespace}->{last_used_time};
+ my @keys_in_lru_order =
+ sort { $last_used_time->{$a} <=> $last_used_time->{$b} } $self->get_keys;
+ return sub {
+ shift(@keys_in_lru_order);
+ };
+ }</pre>
+
+<p>You can set the default discard policy for your driver by overriding default_discard_policy; otherwise the default is 'arbitrary'.</p>
+
+<pre> sub default_discard_policy { 'lru' }</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="TESTING"
+>TESTING</a></h1>
+
+<p>CHI has a standard set of unit tests that should be used to ensure your driver is fully implementing the CHI API.</p>
+
+<p>To use CHI's tests (replacing <i>MyDriver</i> with the name of your driver):</p>
+
+<ul>
+<li>Install Test::Class, and add Test::Class to the build dependencies for your distribution.</li>
+
+<li>Add a module called <i>CHI::Driver::MyDriver::t::CHIDriverTests</i> to your distribution containing:
+<pre> package CHI::Driver::MyDriver::t::CHIDriverTests;
+ use strict;
+ use warnings;
+ use CHI::Test;
+ use base qw(CHI::t::Driver);
+
+ sub new_cache_options {
+ my $self = shift;
+
+ return (
+ $self->SUPER::new_cache_options(),
+ driver_class => 'CHI::Driver::MyDriver',
+
+ # Any other CHI->new parameters for your test driver
+ );
+ }
+
+ 1;</pre>
+</li>
+
+<li>Add a test script called <i>t/CHI-driver-tests.t</i> to your distribution containing:
+<pre> #!perl -w
+ use strict;
+ use warnings;
+ use CHI::Driver::MyDriver::t::CHIDriverTests;
+ CHI::Driver::MyDriver::t::CHIDriverTests->runtests;</pre>
+</li>
+
+<li>You may need to override other methods in <i>CHI::Driver::MyDriver::t::CHIDriverTests</i>, e.g. to skip tests that do not apply to your driver. See CHI::t::Driver::Memory and CHI::t::Driver::File in this distribution for examples.</li>
+</ul>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="AUTHOR"
+>AUTHOR</a></h1>
+
+<p>Jonathan Swartz</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SEE_ALSO"
+>SEE ALSO</a></h1>
+
+<p><a href="http://search.cpan.org/perldoc?CHI" class="podlinkpod"
+>CHI</a>, <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver" class="podlinkpod"
+>CHI::Driver</a></p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="COPYRIGHT_&_LICENSE"
+>COPYRIGHT & LICENSE</a></h1>
+
+<p>Copyright (C) 2007 Jonathan Swartz.</p>
+
+<p>CHI is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.</p>
+
+<p>This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,110 @@
+<html><head><title>CHI::Driver::FastMmap</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:12 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#REQUIREMENTS'>REQUIREMENTS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#CONSTRUCTOR_OPTIONS'>CONSTRUCTOR OPTIONS</a>
+ <li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::FastMmap - Shared memory interprocess cache via mmap'ed files</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> use CHI;
+
+ my $cache = CHI->new(
+ driver => 'FastMmap',
+ root_dir => '/path/to/cache/root',
+ cache_size => '1m'
+ );</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="REQUIREMENTS"
+>REQUIREMENTS</a></h1>
+
+<p>You will need to install <a href="http://search.cpan.org/perldoc?Cache%3A%3AFastMmap" class="podlinkpod"
+>Cache::FastMmap</a> from CPAN to use this driver.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This cache driver uses Cache::FastMmap to store data in an mmap'ed file. It is very fast, and can be used to share data between processes on a single host, though not between hosts.</p>
+
+<p>To support namespaces, this driver takes a directory parameter rather than a file, and creates one Cache::FastMMap file for each namespace.</p>
+
+<p>Because CHI handles serialization automatically, we pass the <code>raw_values</code> flag as 1; and to conform to the CHI API, we pass <code>unlink_on_exit</code> as 0, so that all cache files are permanent.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="CONSTRUCTOR_OPTIONS"
+>CONSTRUCTOR OPTIONS</a></h1>
+
+<dl>
+<dt><a name="root_dir"
+>root_dir</a></dt>
+
+<dd>
+<p>Path to the directory that will contain the share files, one per namespace. Defaults to a directory called 'chi-driver-fastmmap' under the OS default temp directory (e.g. '/tmp' on UNIX).</p>
+
+<dt><a name="dir_create_mode"
+>dir_create_mode</a></dt>
+
+<dd>
+<p>Permissions mode to use when creating directories. Defaults to 0775.</p>
+</dd>
+</dl>
+
+<p>Any other constructor options <a href="http://search.cpan.org/perldoc?CHI#constructor" class="podlinkpod"
+>not recognized by CHI</a> are passed along to <a href="http://search.cpan.org/perldoc?Cache%3A%3AFastMmap-%3Enew" class="podlinkpod"
+>Cache::FastMmap->new</a>.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="METHODS"
+>METHODS</a></h1>
+
+<dl>
+<dt><a name="fm_cache"
+>fm_cache</a></dt>
+
+<dd>
+<p>Returns a handle to the underlying Cache::FastMmap object. You can use this to call FastMmap-specific methods that are not supported by the general API, e.g.</p>
+
+<pre> $self->fm_cache->get_and_set("key", sub { ... });</pre>
+</dd>
+</dl>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,137 @@
+<html><head><title>CHI::Driver::File</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:12 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#CONSTRUCTOR_OPTIONS'>CONSTRUCTOR OPTIONS</a>
+ <li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
+ <li class='indexItem indexItem1'><a href='#TEMPORARY_FILE_RENAME'>TEMPORARY FILE RENAME</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::File - File-based cache using one file per entry in a multi-level directory structure</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> use CHI;
+
+ my $cache = CHI->new(
+ driver => 'File',
+ root_dir => '/path/to/cache/root',
+ depth => 3,
+ max_key_length => 64
+ );</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This cache driver stores data on the filesystem, so that it can be shared between processes on a single machine, or even on multiple machines if using NFS.</p>
+
+<p>Each item is stored in its own file. By default, during a set, a temporary file is created and then atomically renamed to the proper file. While not the most efficient, it eliminates the need for locking (with multiple overlapping sets, the last one "wins") and makes this cache usable in environments like NFS where locking might normally be undesirable.</p>
+
+<p>By default, the base filename is the key itself, with unsafe characters escaped similar to URL escaping. If the escaped key is larger than <a href="#max_key_length" class="podlinkpod"
+>"max_key_length"</a> (default 248 characters), it will be <a href="http://search.cpan.org/perldoc?CHI#key_digester" class="podlinkpod"
+>digested</a>. You may want to lower <a href="#max_key_length" class="podlinkpod"
+>"max_key_length"</a> if you are storing a lot of items as long filenames can be more expensive to work with.</p>
+
+<p>The files are evenly distributed within a multi-level directory structure with a customizable <a href="#depth" class="podlinkpod"
+>"depth"</a>, to minimize the time needed to search for a given entry.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="CONSTRUCTOR_OPTIONS"
+>CONSTRUCTOR OPTIONS</a></h1>
+
+<p>When using this driver, the following options can be passed to CHI->new() in addition to the <a href="http://search.cpan.org/perldoc?general%20constructor%20options#constructor" class="podlinkpod"
+>CHI</a>.</p>
+
+<dl>
+<dt><a name="root_dir"
+>root_dir</a></dt>
+
+<dd>
+<p>The location in the filesystem that will hold the root of the cache. Defaults to a directory called 'chi-driver-file' under the OS default temp directory (e.g. '/tmp' on UNIX). This directory will be created as needed on the first cache set.</p>
+
+<dt><a name="depth"
+>depth</a></dt>
+
+<dd>
+<p>The number of subdirectories deep to place cache files. Defaults to 2. This should be large enough that no leaf directory has more than a few hundred files. Each non-leaf directory contains up to 16 subdirectories (0-9, A-F).</p>
+
+<dt><a name="dir_create_mode"
+>dir_create_mode</a></dt>
+
+<dd>
+<p>Permissions mode to use when creating directories. Defaults to 0775.</p>
+
+<dt><a name="file_create_mode"
+>file_create_mode</a></dt>
+
+<dd>
+<p>Permissions mode to use when creating files, modified by the current umask. Defaults to 0666.</p>
+
+<dt><a name="file_extension"
+>file_extension</a></dt>
+
+<dd>
+<p>Extension to append to filename. Default is ".dat".</p>
+</dd>
+</dl>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="METHODS"
+>METHODS</a></h1>
+
+<dl>
+<dt><a name="path_to_key_(_$key_)"
+>path_to_key ( $key )</a></dt>
+
+<dd>
+<p>Returns the full path to the cache file representing $key, whether or not that entry exists. Returns the empty list if a valid path cannot be computed, for example if the key is too long.</p>
+
+<dt><a name="path_to_namespace"
+>path_to_namespace</a></dt>
+
+<dd>
+<p>Returns the full path to the directory representing this cache's namespace, whether or not it has any entries.</p>
+</dd>
+</dl>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="TEMPORARY_FILE_RENAME"
+>TEMPORARY FILE RENAME</a></h1>
+
+<p>By default, during a set, a temporary file is created and then atomically renamed to the proper file. This eliminates the need for locking. You can subclass and override method <i>generate_temporary_filename</i> to either change the path of the temporary filename, or skip the temporary file and rename altogether by having it return undef.</p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,100 @@
+<html><head><title>CHI::Driver::Memory</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:12 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#CONSTRUCTOR_OPTIONS'>CONSTRUCTOR OPTIONS</a>
+ <li class='indexItem indexItem1'><a href='#DISCARD_POLICY'>DISCARD POLICY</a>
+ <li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::Memory - In-process memory based cache</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> use CHI;
+
+ my $hash = {};
+ my $cache = CHI->new( driver => 'Memory', datastore => $hash );
+
+ my $cache = CHI->new( driver => 'Memory', global => 1 );</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This cache driver stores data on a per-process basis. This is the fastest of the cache implementations, but data can not be shared between processes. Data will remain in the cache until cleared, expired, or the process dies.</p>
+
+<p>To maintain the same semantics as other caches, references to data structures are deep-copied on set and get. Thus, modifications to the original data structure will not affect the data structure stored in the cache, and vica versa. See <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ARawMemory" class="podlinkpod"
+>CHI::Driver::RawMemory</a> for a faster memory cache that sacrifices this behavior.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="CONSTRUCTOR_OPTIONS"
+>CONSTRUCTOR OPTIONS</a></h1>
+
+<p>When using this driver, the following options can be passed to CHI->new() in addition to the <a href="http://search.cpan.org/perldoc?general%20constructor%20options#constructor" class="podlinkpod"
+>CHI</a>. One of <i>datastore</i> or <i>global</i> must be specified, or else a warning (possibly an error eventually) will be thrown.</p>
+
+<dl>
+<dt><a name="datastore_[HASH]"
+>datastore [HASH]</a></dt>
+
+<dd>
+<p>A hash to be used for storage. Within the hash, each namespace is used as a key to a second-level hash. This hash may be passed to multiple CHI::Driver::Memory constructors.</p>
+
+<dt><a name="global_[BOOL]"
+>global [BOOL]</a></dt>
+
+<dd>
+<p>Use a standard global datastore. Multiple caches created with this flag will see the same data. Before 0.21, this was the default behavior; now it must be specified explicitly (to avoid accidentally sharing the same datastore in unrelated code).</p>
+</dd>
+</dl>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DISCARD_POLICY"
+>DISCARD POLICY</a></h1>
+
+<p>For <a href="http://search.cpan.org/perldoc?size%20aware" class="podlinkpod"
+>CHI/SIZE AWARENESS</a> caches, this driver implements an 'LRU' policy, which discards the least recently used items first. This is the default policy.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SEE_ALSO"
+>SEE ALSO</a></h1>
+
+<p><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ARawMemory" class="podlinkpod"
+>CHI::Driver::RawMemory</a>, <a href="http://search.cpan.org/perldoc?CHI" class="podlinkpod"
+>CHI</a></p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,46 @@
+<html><head><title>CHI::Driver::Metacache</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:12 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::Metacache - Metacache for internal CHI use</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> $cache->metacache->get($meta_key);
+ $cache->metacache->set($meta_key => $value);</pre>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,56 @@
+<html><head><title>CHI::Driver::Null</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:12 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::Null - Nothing is cached</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> use CHI;
+
+ my $cache = CHI->new(driver => 'Null');
+ $cache->set('key', 5);
+ my $value = $cache->get('key'); # returns undef</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This cache driver implements the full CHI interface without ever actually storing items. Useful for disabling caching in an application, for example.</p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,101 @@
+<html><head><title>CHI::Driver::RawMemory</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:12 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#CONSTRUCTOR_OPTIONS'>CONSTRUCTOR OPTIONS</a>
+ <li class='indexItem indexItem1'><a href='#SIZE_AWARENESS'>SIZE AWARENESS</a>
+ <li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver::RawMemory - In-process memory cache that stores direct references</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> use CHI;
+
+ my $hash = {};
+ my $cache = CHI->new( driver => 'RawMemory', datastore => $hash );
+
+ my $cache = CHI->new( driver => 'RawMemory', global => 1 );</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This is a subclass of <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AMemory" class="podlinkpod"
+>CHI::Driver::Memory</a> that stores references to data structures directly instead of serializing / deserializing. This makes the cache faster at getting and setting complex data structures, but unlike most drivers, modifications to the original data structure <i>will</i> affect the data structure stored in the cache, and vica versa. e.g.</p>
+
+<pre> my $cache = CHI->new( driver => 'Memory', global => 1 );
+ my $lst = ['foo'];
+ $cache->set('key' => $lst); # serializes $lst before storing
+ $cache->get('key'); # returns ['foo']
+ $lst->[0] = 'bar';
+ $cache->get('key'); # returns ['foo']
+
+ my $cache = CHI->new( driver => 'RawMemory', global => 1 );
+ my $lst = ['foo'];
+ $cache->set('key' => $lst); # stores $lst directly
+ $cache->get('key'); # returns ['foo']
+ $lst->[0] = 'bar';
+ $cache->get('key'); # returns ['bar']!</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="CONSTRUCTOR_OPTIONS"
+>CONSTRUCTOR OPTIONS</a></h1>
+
+<p>Same as <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AMemory" class="podlinkpod"
+>CHI::Driver::Memory</a>.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SIZE_AWARENESS"
+>SIZE AWARENESS</a></h1>
+
+<p>For the purpose of <a href="http://search.cpan.org/perldoc?CHI#SIZE_AWARENESS" class="podlinkpod"
+>size-awareness</a>, all items count as size 1 for this driver. (Because data structures are not serialized, there's no good way to determine their size.)</p>
+
+<pre> # Keep a maximum of 10 items in cache
+ #
+ my $cache = CHI->new( driver => 'RawMemory', datastore => {}, max_size => 10 );</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SEE_ALSO"
+>SEE ALSO</a></h1>
+
+<p><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AMemory" class="podlinkpod"
+>CHI::Driver::Memory</a>, <a href="http://search.cpan.org/perldoc?CHI" class="podlinkpod"
+>CHI</a></p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,52 @@
+<html><head><title>CHI::Driver</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Driver - Base class for all CHI drivers</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>This is the base class that all CHI drivers inherit from.
+It provides the methods that one calls on $cache handles,
+such as get() and set().</p>
+
+<p>See <a href="http://search.cpan.org/perldoc?CHI#METHODS" class="podlinkpod"
+>"METHODS" in CHI</a> for documentation on $cache methods,
+and <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ADevelopment" class="podlinkpod"
+>CHI::Driver::Development</a> for documentation on creating new subclasses of CHI::Driver.</p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,141 @@
+<html><head><title>CHI::Stats</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#STATISTICS'>STATISTICS</a>
+ <li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI::Stats - Record and report per-namespace cache statistics</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> # Turn on statistics collection
+ CHI->stats->enable();
+
+ # Perform cache operations
+
+ # Flush statistics to logs
+ CHI->stats->flush();
+
+ ...
+
+ # Parse logged statistics
+ my $results = CHI->stats->parse_stats_logs($file1, ...);</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>CHI can record statistics, such as number of hits, misses and sets, on a per-namespace basis and log the results to your <a href="http://search.cpan.org/perldoc?Log%3A%3AAny" class="podlinkpod"
+>Log::Any</a> logger. You can then parse the logs to get a combined summary.</p>
+
+<p>A single CHI::Stats object is maintained for each CHI root class, and tallies statistics over any number of CHI::Driver objects.</p>
+
+<p>Statistics are reported when you call the <a href="#flush" class="podlinkpod"
+>"flush"</a> method. You can choose to this once at process end, or on a periodic basis.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="STATISTICS"
+>STATISTICS</a></h1>
+
+<p>The following statistics are tracked:</p>
+
+<ul>
+<li>absent_misses - Number of gets that failed due to item not being in the cache</li>
+
+<li>expired_misses - Number of gets that failed due to item expiring</li>
+
+<li>get_errors - Number of caught runtime errors during gets</li>
+
+<li>hits - Number of gets that succeeded</li>
+
+<li>set_key_size - Number of bytes in set keys (divide by number of sets to get average)</li>
+
+<li>set_value_size - Number of bytes in set values (divide by number of sets to get average)</li>
+
+<li>sets - Number of sets</li>
+
+<li>set_errors - Number of caught runtime errors during sets</li>
+</ul>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="METHODS"
+>METHODS</a></h1>
+
+<dl>
+<dt><a name="enable_=item_disable_=item_enabled"
+>enable =item disable =item enabled</a></dt>
+
+<dd>
+<p>Enable, disable, and query the current enabled status.</p>
+
+<p>When stats are enabled, each new cache object will collect statistics. Enabling and disabling does not affect existing cache objects. e.g.</p>
+
+<pre> my $cache1 = CHI->new(...);
+ CHI->stats->enable();
+ # $cache1 will not collect statistics
+ my $cache2 = CHI->new(...);
+ CHI->stats->disable();
+ # $cache2 will continue to collect statistics</pre>
+
+<dt><a name="flush"
+>flush</a></dt>
+
+<dd>
+<p>Log all statistics to <a href="http://search.cpan.org/perldoc?Log%3A%3AAny" class="podlinkpod"
+>Log::Any</a> (at Info level in the CHI::Stats category), then clear statistics from memory. There is one log message per cache label and namespace, looking like:</p>
+
+<pre> CHI stats: namespace='Foo'; cache='File'; start=20090102:12:53:05; end=20090102:12:58:05; absent_misses=10; expired_misses=20; hits=50; set_key_size=6; set_value_size=20; sets=30</pre>
+
+<dt><a name="parse_stats_logs_(log1,_log2,_...)"
+>parse_stats_logs (log1, log2, ...)</a></dt>
+
+<dd>
+<p>Parses logs output by CHI::Stats and returns a listref of stats totals by root class, cache label, and namespace. e.g.</p>
+
+<pre> [
+ {root_class => 'CHI', cache =>'File', namespace => 'Foo', absent_misses => 100, expired_misses => 200, ... },
+ {root_class => 'CHI', cache =>'File', namespace => 'Bar', ... },
+ ]</pre>
+
+<p>Lines with the root class, cache label, and namespace are summed together. Non-stats lines are ignored.</p>
+
+<p>Each parameter to this method may be a filename or a reference to an open filehandle.</p>
+</dd>
+</dl>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,1110 @@
+<html><head><title>CHI</title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
+<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
+
+</head>
+<body class='pod'>
+<!--
+ generated by Pod::Simple::HTML v3.15,
+ using Pod::Simple::PullParser v3.15,
+ under Perl v5.012002 at Wed Mar 2 00:52:11 2011 GMT.
+
+ If you want to change this HTML document, you probably shouldn't do that
+ by changing it directly. Instead, see about changing the calling options
+ to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
+ then reconverting this document from the Pod source.
+ When in doubt, email the author of Pod::Simple::HTML for advice.
+ See 'perldoc Pod::Simple::HTML' for more info.
+
+-->
+
+<!-- start doc -->
+<a name='___top' class='dummyTopAnchor' ></a>
+
+<div class='indexgroup'>
+<ul class='indexList indexList1'>
+ <li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
+ <li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
+ <li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
+ <li class='indexItem indexItem1'><a href='#FEATURES'>FEATURES</a>
+ <li class='indexItem indexItem1'><a href='#CONSTRUCTOR'>CONSTRUCTOR</a>
+ <li class='indexItem indexItem1'><a href='#INSTANCE_METHODS'>INSTANCE METHODS</a>
+ <ul class='indexList indexList2'>
+ <li class='indexItem indexItem2'><a href='#Getting_and_setting'>Getting and setting</a>
+ <li class='indexItem indexItem2'><a href='#Removing_and_expiring'>Removing and expiring</a>
+ <li class='indexItem indexItem2'><a href='#Inspecting_keys'>Inspecting keys</a>
+ <li class='indexItem indexItem2'><a href='#Namespace_operations'>Namespace operations</a>
+ <li class='indexItem indexItem2'><a href='#Multiple_key%2Fvalue_operations'>Multiple key/value operations</a>
+ <li class='indexItem indexItem2'><a href='#Property_accessors'>Property accessors</a>
+ <li class='indexItem indexItem2'><a href='#Deprecated_methods'>Deprecated methods</a>
+ </ul>
+ <li class='indexItem indexItem1'><a href='#DURATION_EXPRESSIONS'>DURATION EXPRESSIONS</a>
+ <li class='indexItem indexItem1'><a href='#KEY_AND_VALUE_TRANSFORMATIONS'>KEY AND VALUE TRANSFORMATIONS</a>
+ <ul class='indexList indexList2'>
+ <li class='indexItem indexItem2'><a href='#Key_transformations'>Key transformations</a>
+ <li class='indexItem indexItem2'><a href='#Value_transformations'>Value transformations</a>
+ </ul>
+ <li class='indexItem indexItem1'><a href='#SUBCACHES'>SUBCACHES</a>
+ <ul class='indexList indexList2'>
+ <li class='indexItem indexItem2'><a href='#L1_cache'>L1 cache</a>
+ <li class='indexItem indexItem2'><a href='#Mirror_cache'>Mirror cache</a>
+ <li class='indexItem indexItem2'><a href='#Creating_subcaches'>Creating subcaches</a>
+ <li class='indexItem indexItem2'><a href='#Common_subcache_behaviors'>Common subcache behaviors</a>
+ <li class='indexItem indexItem2'><a href='#Multiple_subcaches'>Multiple subcaches</a>
+ <li class='indexItem indexItem2'><a href='#Methods_for_parent_caches'>Methods for parent caches</a>
+ <li class='indexItem indexItem2'><a href='#Methods_for_subcaches'>Methods for subcaches</a>
+ <li class='indexItem indexItem2'><a href='#Developing_new_kinds_of_subcaches'>Developing new kinds of subcaches</a>
+ </ul>
+ <li class='indexItem indexItem1'><a href='#SIZE_AWARENESS'>SIZE AWARENESS</a>
+ <ul class='indexList indexList2'>
+ <li class='indexItem indexItem2'><a href='#Maximum_size_and_discard_policies'>Maximum size and discard policies</a>
+ <li class='indexItem indexItem2'><a href='#Appropriate_drivers'>Appropriate drivers</a>
+ </ul>
+ <li class='indexItem indexItem1'><a href='#AVAILABILITY_OF_DRIVERS'>AVAILABILITY OF DRIVERS</a>
+ <li class='indexItem indexItem1'><a href='#PERFORMANCE_COMPARISON_OF_DRIVERS'>PERFORMANCE COMPARISON OF DRIVERS</a>
+ <li class='indexItem indexItem1'><a href='#DEVELOPING_NEW_DRIVERS'>DEVELOPING NEW DRIVERS</a>
+ <li class='indexItem indexItem1'><a href='#LOGGING'>LOGGING</a>
+ <li class='indexItem indexItem1'><a href='#STATS'>STATS</a>
+ <li class='indexItem indexItem1'><a href='#RELATION_TO_OTHER_MODULES'>RELATION TO OTHER MODULES</a>
+ <ul class='indexList indexList2'>
+ <li class='indexItem indexItem2'><a href='#Cache%3A%3ACache'>Cache::Cache</a>
+ <li class='indexItem indexItem2'><a href='#Cache'>Cache</a>
+ <li class='indexItem indexItem2'><a href='#Cache%3A%3AMemcached%2C_Cache%3A%3AFastMmap%2C_etc.'>Cache::Memcached, Cache::FastMmap, etc.</a>
+ </ul>
+ <li class='indexItem indexItem1'><a href='#SUPPORT_AND_DOCUMENTATION'>SUPPORT AND DOCUMENTATION</a>
+ <li class='indexItem indexItem1'><a href='#TODO'>TODO</a>
+ <li class='indexItem indexItem1'><a href='#ACKNOWLEDGMENTS'>ACKNOWLEDGMENTS</a>
+ <li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
+</ul>
+</div>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="NAME"
+>NAME</a></h1>
+
+<p>CHI - Unified cache handling interface</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SYNOPSIS"
+>SYNOPSIS</a></h1>
+
+<pre> use CHI;
+
+ # Choose a standard driver
+ #
+ my $cache = CHI->new( driver => 'Memory', global => 1 );
+ my $cache = CHI->new( driver => 'RawMemory', global => 1 );
+ my $cache = CHI->new( driver => 'File',
+ root_dir => '/path/to/root'
+ );
+ my $cache = CHI->new( driver => 'FastMmap',
+ root_dir => '/path/to/root',
+ cache_size => '1k'
+ );
+ my $cache = CHI->new( driver => 'Memcached::libmemcached',
+ servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
+ l1_cache => { driver => 'FastMmap', root_dir => '/path/to/root' }
+ );
+ my $cache = CHI->new( driver => 'DBI',
+ dbh => $dbh
+ );
+ my $cache = CHI->new( driver => 'BerkeleyDB',
+ root_dir => '/path/to/root'
+ );
+
+ # Create your own driver
+ #
+ my $cache = CHI->new( driver_class => 'My::Special::Driver', ... );
+
+ # Cache operations
+ #
+ my $customer = $cache->get($name);
+ if ( !defined $customer ) {
+ $customer = get_customer_from_db($name);
+ $cache->set( $name, $customer, "10 minutes" );
+ }
+ my $customer2 = $cache->compute($name2, "10 minutes", sub {
+ get_customer_from_db($name2)
+ });
+ $cache->remove($name);</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DESCRIPTION"
+>DESCRIPTION</a></h1>
+
+<p>CHI provides a unified caching API, designed to assist a developer in persisting data for a specified period of time.</p>
+
+<p>The CHI interface is implemented by driver classes that support fetching, storing and clearing of data. Driver classes exist or will exist for the gamut of storage backends available to Perl, such as memory, plain files, memory mapped files, memcached, and DBI.</p>
+
+<p>CHI is intended as an evolution of DeWitt Clinton's <a href="http://search.cpan.org/perldoc?Cache%3A%3ACache" class="podlinkpod"
+>Cache::Cache</a> package, adhering to the basic Cache API but adding new features and addressing limitations in the Cache::Cache implementation.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="FEATURES"
+>FEATURES</a></h1>
+
+<ul>
+<li>Easy to create new drivers</li>
+
+<li>Uniform support for namespaces</li>
+
+<li>Automatic serialization of keys and values</li>
+
+<li>Multilevel caches</li>
+
+<li>Probabilistic expiration and busy locks, to reduce cache miss stampedes</li>
+
+<li>Optional logging and statistics collection of cache activity</li>
+</ul>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="CONSTRUCTOR"
+>CONSTRUCTOR</a></h1>
+
+<p>To create a new cache handle, call CHI->new. It takes the following common options. All are optional, except that either <i>driver</i> or <i>driver_class</i> must be passed.</p>
+
+<dl>
+<dt><a name="driver_[STRING]"
+>driver [STRING]</a></dt>
+
+<dd>
+<p>The name of a standard driver to drive the cache, for example "Memory" or "File". CHI will prefix the string with "CHI::Driver::".</p>
+
+<dt><a name="driver_class_[STRING]"
+>driver_class [STRING]</a></dt>
+
+<dd>
+<p>The exact CHI::Driver subclass to drive the cache, for example "My::Memory::Driver".</p>
+
+<dt><a name="expires_in_[DURATION]"
+>expires_in [DURATION]</a></dt>
+
+<dd>
+<dt><a name="expires_at_[INT]"
+>expires_at [INT]</a></dt>
+
+<dd>
+<dt><a name="expires_variance_[FLOAT]"
+>expires_variance [FLOAT]</a></dt>
+
+<dd>
+<p>Provide default values for the corresponding <a href="#set" class="podlinkpod"
+>"set"</a> options.</p>
+
+<dt><a name="key_digester_[STRING|HASHREF|OBJECT]"
+>key_digester [STRING|HASHREF|OBJECT]</a></dt>
+
+<dd>
+<p>Digest algorithm to use on keys longer than <a href="#max_key_length" class="podlinkpod"
+>"max_key_length"</a> - e.g. "MD5", "SHA-1", or "SHA-256".</p>
+
+<p>Can be a <a href="http://search.cpan.org/perldoc?Digest" class="podlinkpod"
+>Digest</a> object, or a string or hashref which will passed to Digest->new(). You will need to ensure Digest is installed to use these options.</p>
+
+<p>Default is "MD5".</p>
+
+<dt><a name="label_[STRING]"
+>label [STRING]</a></dt>
+
+<dd>
+<p>A label for the cache as a whole, independent of namespace - e.g. "web-file-cache". Used when referring to the cache in logs, statistics, and error messages. By default, set to <a href="#short_driver_name" class="podlinkpod"
+>"short_driver_name"</a>.</p>
+
+<dt><a name="l1_cache_[HASHREF]"
+>l1_cache [HASHREF]</a></dt>
+
+<dd>
+<p>Add an L1 cache as a subcache. See <a href="#SUBCACHES" class="podlinkpod"
+>"SUBCACHES"</a>.</p>
+
+<dt><a name="max_key_length_[INT]"
+>max_key_length [INT]</a></dt>
+
+<dd>
+<p>Keys over this size will be <a href="http://search.cpan.org/perldoc?key_digester" class="podlinkpod"
+>digested</a>. The default is driver-specific; <a href="http://search.cpan.org/perldoc?File" class="podlinkpod"
+>CHI::Driver::File</a>, for example, defaults this to 240 due to file system limits. For most drivers there is no maximum.</p>
+
+<dt><a name="mirror_cache_[HASHREF]"
+>mirror_cache [HASHREF]</a></dt>
+
+<dd>
+<p>Add an mirror cache as a subcache. See <a href="#SUBCACHES" class="podlinkpod"
+>"SUBCACHES"</a>.</p>
+
+<dt><a name="namespace_[STRING]"
+>namespace [STRING]</a></dt>
+
+<dd>
+<p>Identifies a namespace that all cache entries for this object will be in. This allows easy separation of multiple, distinct caches without worrying about key collision.</p>
+
+<p>Suggestions for easy namespace selection:</p>
+
+<ul>
+<li>In a class, use the class name:
+<pre> my $cache = CHI->new(namespace => __PACKAGE__, ...);</pre>
+</li>
+
+<li>In a script, use the script's absolute path name:
+<pre> use Cwd qw(realpath);
+ my $cache = CHI->new(namespace => realpath($0), ...);</pre>
+</li>
+
+<li>In a web template, use the template name. For example, in Mason, $m->cache will set the namespace to the current component path.</li>
+</ul>
+
+<p>Defaults to 'Default' if not specified.</p>
+
+<dt><a name="serializer_[STRING|HASHREF|OBJECT]"
+>serializer [STRING|HASHREF|OBJECT]</a></dt>
+
+<dd>
+<p>An object to use for serializing data before storing it in the cache, and deserializing data after retrieving it from the cache.</p>
+
+<p>If this is a string, a <a href="http://search.cpan.org/perldoc?Data%3A%3ASerializer" class="podlinkpod"
+>Data::Serializer</a> object will be created, with the string passed as the 'serializer' option and raw=1. Common options include 'Storable', 'Data::Dumper', and 'YAML'. If this is a hashref, <a href="http://search.cpan.org/perldoc?Data%3A%3ASerializer-%3Enew" class="podlinkpod"
+>Data::Serializer</a> will be called with the hash. You will need to ensure Data::Serializer is installed to use these options.</p>
+
+<p>Otherwise, this must be a <a href="http://search.cpan.org/perldoc?Data%3A%3ASerializer" class="podlinkpod"
+>Data::Serializer</a> object or another object that implements <i>serialize()</i> and <i>deserialize()</i>.</p>
+
+<p>e.g.</p>
+
+<pre> # Serialize using raw Data::Dumper
+ my $cache = CHI->new(serializer => 'Data::Dumper');
+
+ # Serialize using Data::Dumper, compressed and (per Data::Serializer defaults) hex-encoded
+ my $cache = CHI->new(serializer => { serializer => 'Data::Dumper', compress => 1 });
+
+ # Serialize using custom object
+ my $cache = CHI->new(serializer => My::Custom::Serializer->new())</pre>
+
+<p>The default is to use raw Storable.</p>
+
+<dt><a name="key_serializer_[STRING|HASHREF|OBJECT]"
+>key_serializer [STRING|HASHREF|OBJECT]</a></dt>
+
+<dd>
+<p>An object to use for serializing keys that are references. See <a href="#serializer" class="podlinkpod"
+>"serializer"</a> above for the different ways this can be passed in. The default is to use JSON in canonical mode (sorted hash keys).</p>
+
+<dt><a name="on_get_error_[STRING|CODEREF]"
+>on_get_error [STRING|CODEREF]</a></dt>
+
+<dd>
+<dt><a name="on_set_error_[STRING|CODEREF]"
+>on_set_error [STRING|CODEREF]</a></dt>
+
+<dd>
+<p>How to handle runtime errors occurring during cache gets and cache sets, which may or may not be considered fatal in your application. Options are:</p>
+
+<ul>
+<li>log (the default) - log an error, or ignore if no logger is set - see <a href="#LOGGING" class="podlinkpod"
+>"LOGGING"</a></li>
+
+<li>ignore - do nothing</li>
+
+<li>warn - call warn() with an appropriate message</li>
+
+<li>die - call die() with an appropriate message</li>
+
+<li><i>coderef</i> - call this code reference with three arguments: an appropriate message, the key, and the original raw error message</li>
+</ul>
+</dd>
+</dl>
+
+<p>Some drivers will take additional constructor options. For example, the File driver takes <code>root_dir</code> and <code>depth</code> options.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="INSTANCE_METHODS"
+>INSTANCE METHODS</a></h1>
+
+<p>The following methods can be called on any cache handle returned from CHI->new(). They are implemented in the <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver" class="podlinkpod"
+>CHI::Driver</a> package.</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Getting_and_setting"
+>Getting and setting</a></h2>
+
+<dl>
+<dt><a name="get(_$key,_[option_=>_value,_...]_)"
+>get( $key, [option => value, ...] )</a></dt>
+
+<dd>
+<p>Returns the data associated with <i>$key</i>. If <i>$key</i> does not exist or has expired, returns undef. Expired items are not automatically removed and may be examined with <a href="#get_object" class="podlinkpod"
+>"get_object"</a> or <a href="#get_expires_at" class="podlinkpod"
+>"get_expires_at"</a>.</p>
+
+<p><i>$key</i> may be followed by one or more name/value parameters:</p>
+
+<dl>
+<dt><a name="expire_if_[CODEREF]"
+>expire_if [CODEREF]</a></dt>
+
+<dd>
+<p>If <i>$key</i> exists and has not expired, call code reference with the <a href="http://search.cpan.org/perldoc?CHI%3A%3ACacheObject" class="podlinkpod"
+>CHI::CacheObject</a> as a single parameter. If code returns a true value, <code>get</code> returns undef as if the item were expired. For example, to treat the cache as expired if <i>$file</i> has changed since the value was computed:</p>
+
+<pre> $cache->get('foo', expire_if => sub { $_[0]->created_at < (stat($file))[9] });</pre>
+
+<dt><a name="busy_lock_[DURATION]"
+>busy_lock [DURATION]</a></dt>
+
+<dd>
+<p>If the value has expired, set its expiration time to the current time plus the specified <a href="#DURATION_EXPRESSIONS" class="podlinkpod"
+>duration</a> before returning undef. This is used to prevent multiple processes from recomputing the same expensive value simultaneously. The problem with this technique is that it doubles the number of writes performed - see <a href="#expires_variance" class="podlinkpod"
+>"expires_variance"</a> for another technique.</p>
+</dd>
+</dl>
+
+<dt><a name="set(_$key,_$data,_[$expires_in_|_"now"_|_"never"_|_options]_)"
+>set( $key, $data, [$expires_in | "now" | "never" | options] )</a></dt>
+
+<dd>
+<p>Associates <i>$data</i> with <i>$key</i> in the cache, overwriting any existing entry. Returns <i>$data</i>.</p>
+
+<p>The third argument to <code>set</code> is optional, and may be either a scalar or a hash reference. If it is a scalar, it may be the string "now", the string "never", or else a duration treated as an <i>expires_in</i> value described below. If it is a hash reference, it may contain one or more of the following options. Most of these options can be provided with defaults in the cache constructor.</p>
+
+<dl>
+<dt><a name="expires_in_[DURATION]"
+>expires_in [DURATION]</a></dt>
+
+<dd>
+<p>Amount of time (in seconds) until this data expires.</p>
+
+<dt><a name="expires_at_[INT]"
+>expires_at [INT]</a></dt>
+
+<dd>
+<p>The epoch time at which the data expires.</p>
+
+<dt><a name="expires_variance_[FLOAT]"
+>expires_variance [FLOAT]</a></dt>
+
+<dd>
+<p>Controls the variable expiration feature, which allows items to expire a little earlier than the stated expiration time to help prevent cache miss stampedes.</p>
+
+<p>Value is between 0.0 and 1.0, with 0.0 meaning that items expire exactly when specified (feature is disabled), and 1.0 meaning that items might expire anytime from now til the stated expiration time. The default is 0.0. A setting of 0.10 to 0.25 would introduce a small amount of variation without interfering too much with intended expiration times.</p>
+
+<p>The probability of expiration increases as a function of how far along we are in the potential expiration window, with the probability being near 0 at the beginning of the window and approaching 1 at the end.</p>
+
+<p>For example, in all of the following cases, an item might be considered expired any time between 15 and 20 minutes, with about a 20% chance at 16 minutes, a 40% chance at 17 minutes, and a 100% chance at 20 minutes.</p>
+
+<pre> my $cache = CHI->new ( ..., expires_variance => 0.25, ... );
+ $cache->set($key, $value, '20 min');
+ $cache->set($key, $value, { expires_at => time() + 20*60 });
+
+ my $cache = CHI->new ( ... );
+ $cache->set($key, $value, { expires_in => '20 min', expires_variance => 0.25 });</pre>
+
+<p>CHI will make a new probabilistic choice every time it needs to know whether an item has expired (i.e. it does not save the results of its determination), so you can get situations like this:</p>
+
+<pre> my $value = $cache->get($key); # returns undef (indicating expired)
+ my $value = $cache->get($key); # returns valid value this time!
+
+ if ($cache->is_valid($key)) # returns undef (indicating expired)
+ if ($cache->is_valid($key)) # returns true this time!</pre>
+
+<p>Typical applications won't be affected by this, since the object is recomputed as soon as it is determined to be expired. But it's something to be aware of.</p>
+</dd>
+</dl>
+
+<dt><a name="compute(_$key,_$set_options,_$code_)"
+>compute( $key, $set_options, $code )</a></dt>
+
+<dd>
+<p>Combines the <code>get</code> and <code>set</code> operations in a single call. Attempts to get <i>$key</i>; if successful, returns the value. Otherwise, calls <i>$code</i> and uses the return value as the new value for <i>$key</i>, which is then returned. <i>$set_options</i> is a scalar or hash reference, used as the third argument to set.</p>
+
+<pre> $cache->compute($key, '5min', sub {
+ # compute and return value for $key here
+ });</pre>
+
+<p>This method will eventually support the ability to recompute a value in the background just before it actually expires, so that users are not impacted by recompute time.</p>
+
+<p>Note: Prior to version 0.40, the last two arguments were in reverse order; both will be accepted for backward compatibility. We think the coderef looks better at the end.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Removing_and_expiring"
+>Removing and expiring</a></h2>
+
+<dl>
+<dt><a name="remove(_$key_)"
+>remove( $key )</a></dt>
+
+<dd>
+<p>Remove the data associated with the <i>$key</i> from the cache.</p>
+
+<dt><a name="expire(_$key_)"
+>expire( $key )</a></dt>
+
+<dd>
+<p>If <i>$key</i> exists, expire it by setting its expiration time into the past. Does not necessarily remove the data. Since this involves essentially setting the value again, <code>remove</code> may be more efficient for some drivers.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Inspecting_keys"
+>Inspecting keys</a></h2>
+
+<dl>
+<dt><a name="is_valid(_$key_)"
+>is_valid( $key )</a></dt>
+
+<dd>
+<p>Returns a boolean indicating whether <i>$key</i> exists in the cache and has not expired. Note: Expiration may be determined probabilistically if <a href="#expires_variance" class="podlinkpod"
+>"expires_variance"</a> was used.</p>
+
+<dt><a name="exists_and_is_expired(_$key_)"
+>exists_and_is_expired( $key )</a></dt>
+
+<dd>
+<p>Returns a boolean indicating whether <i>$key</i> exists in the cache and has expired. Note: Expiration may be determined probabilistically if <a href="#expires_variance" class="podlinkpod"
+>"expires_variance"</a> was used.</p>
+
+<dt><a name="get_expires_at(_$key_)"
+>get_expires_at( $key )</a></dt>
+
+<dd>
+<p>Returns the epoch time at which <i>$key</i> definitively expires. Returns undef if the key does not exist or it has no expiration time.</p>
+
+<dt><a name="get_object(_$key_)"
+>get_object( $key )</a></dt>
+
+<dd>
+<p>Returns a <a href="http://search.cpan.org/perldoc?CHI%3A%3ACacheObject" class="podlinkpod"
+>CHI::CacheObject</a> object containing data about the entry associated with <i>$key</i>, or undef if no such key exists. The object will be returned even if the entry has expired, as long as it has not been removed.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Namespace_operations"
+>Namespace operations</a></h2>
+
+<dl>
+<dt><a name="clear(_)"
+>clear( )</a></dt>
+
+<dd>
+<p>Remove all entries from the namespace.</p>
+
+<dt><a name="get_keys(_)"
+>get_keys( )</a></dt>
+
+<dd>
+<p>Returns a list of keys in the namespace. This may or may not include expired keys, depending on the driver.</p>
+
+<p>The keys may not look the same as they did when passed into <a href="#set" class="podlinkpod"
+>"set"</a>; they may have been serialized, utf8 encoded, and/or digested (see <a href="#KEY_AND_VALUE_TRANSFORMATIONS" class="podlinkpod"
+>"KEY AND VALUE TRANSFORMATIONS"</a>). However, they may still be passed back into <a href="#get" class="podlinkpod"
+>"get"</a>, <a href="#set" class="podlinkpod"
+>"set"</a>, etc. to access the same underlying objects. i.e. the following code is guaranteed to produce all key/value pairs from the cache:</p>
+
+<pre> map { ($_, $c->get($_)) } $c->get_keys()</pre>
+
+<dt><a name="purge(_)"
+>purge( )</a></dt>
+
+<dd>
+<p>Remove all entries that have expired from the namespace associated with this cache instance. Warning: May be very inefficient, depending on the number of keys and the driver.</p>
+
+<dt><a name="get_namespaces(_)"
+>get_namespaces( )</a></dt>
+
+<dd>
+<p>Returns a list of namespaces associated with the cache. This may or may not include empty namespaces, depending on the driver.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Multiple_key/value_operations"
+>Multiple key/value operations</a></h2>
+
+<p>The methods in this section process multiple keys and/or values at once. By default these are implemented with the obvious map operations, but some cache drivers (e.g. <a href="http://search.cpan.org/perldoc?Cache%3A%3AMemcached" class="podlinkpod"
+>Cache::Memcached</a>) can override them with more efficient implementations.</p>
+
+<dl>
+<dt><a name="get_multi_arrayref(_$keys_)"
+>get_multi_arrayref( $keys )</a></dt>
+
+<dd>
+<p>Get the keys in list reference <i>$keys</i>, and return a list reference of the same length with corresponding values or undefs.</p>
+
+<dt><a name="get_multi_hashref(_$keys_)"
+>get_multi_hashref( $keys )</a></dt>
+
+<dd>
+<p>Like <a href="#get_multi_arrayref" class="podlinkpod"
+>"get_multi_arrayref"</a>, but returns a hash reference with each key in <i>$keys</i> mapping to its corresponding value or undef. Will only work with scalar keys.</p>
+
+<dt><a name="set_multi(_$key_values,_$set_options_)"
+>set_multi( $key_values, $set_options )</a></dt>
+
+<dd>
+<p>Set the multiple keys and values provided in hash reference <i>$key_values</i>. <i>$set_options</i> is a scalar or hash reference, used as the third argument to set. Will only work with scalar keys.</p>
+
+<dt><a name="remove_multi(_$keys_)"
+>remove_multi( $keys )</a></dt>
+
+<dd>
+<p>Removes the keys in list reference <i>$keys</i>.</p>
+
+<dt><a name="dump_as_hash(_)"
+>dump_as_hash( )</a></dt>
+
+<dd>
+<p>Returns a hash reference containing all the non-expired keys and values in the cache.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Property_accessors"
+>Property accessors</a></h2>
+
+<dl>
+<dt><a name="driver_class(_)"
+>driver_class( )</a></dt>
+
+<dd>
+<p>Returns the full name of the driver class. e.g.</p>
+
+<pre> CHI->new(driver=>'File')->driver_class
+ => CHI::Driver::File
+ CHI->new(driver_class=>'CHI::Driver::File')->driver_class
+ => CHI::Driver::File
+ CHI->new(driver_class=>'My::Driver::File')->driver_class
+ => My::Driver::File</pre>
+
+<p>You should use this rather than <code>ref()</code>. Due to some subclassing tricks CHI employs, the actual class of the object is neither guaranteed nor likely to be the driver class.</p>
+
+<dt><a name="short_driver_name(_)"
+>short_driver_name( )</a></dt>
+
+<dd>
+<p>Returns the name of the driver class, minus the CHI::Driver:: prefix, if any. e.g.</p>
+
+<pre> CHI->new(driver=>'File')->short_driver_name
+ => File
+ CHI->new(driver_class=>'CHI::Driver::File')->short_driver_name
+ => File
+ CHI->new(driver_class=>'My::Driver::File')->short_driver_name
+ => My::Driver::File</pre>
+
+<dt><a name="Standard_read-write_accessors"
+>Standard read-write accessors</a></dt>
+
+<dd>
+<pre> expires_in
+ expires_at
+ expires_variance
+ label
+ on_get_error
+ on_set_error</pre>
+
+<dt><a name="Standard_read-only_accessors"
+>Standard read-only accessors</a></dt>
+
+<dd>
+<pre> namespace
+ serializer</pre>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Deprecated_methods"
+>Deprecated methods</a></h2>
+
+<p>The following methods are deprecated and will be removed in a later version:</p>
+
+<pre> is_empty</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DURATION_EXPRESSIONS"
+>DURATION EXPRESSIONS</a></h1>
+
+<p>Duration expressions, which appear in the <a href="#set" class="podlinkpod"
+>"set"</a> command and various other parts of the API, are parsed by <a href="http://search.cpan.org/perldoc?Time%3A%3ADuration%3A%3AParse" class="podlinkpod"
+>Time::Duration::Parse</a>. A duration is either a plain number, which is treated like a number of seconds, or a number and a string representing time units where the string is one of:</p>
+
+<pre> s second seconds sec secs
+ m minute minutes min mins
+ h hr hour hours
+ d day days
+ w week weeks
+ M month months
+ y year years</pre>
+
+<p>e.g. the following are all valid duration expressions:</p>
+
+<pre> 25
+ 3s
+ 5 seconds
+ 1 minute and ten seconds
+ 1 hour</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="KEY_AND_VALUE_TRANSFORMATIONS"
+>KEY AND VALUE TRANSFORMATIONS</a></h1>
+
+<p>CHI strives to accept arbitrary keys and values for caching regardless of the limitations of the underlying driver.</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Key_transformations"
+>Key transformations</a></h2>
+
+<ul>
+<li>Keys that are references are serialized - see <a href="#key_serializer" class="podlinkpod"
+>"key_serializer"</a>.</li>
+
+<li>Keys with wide (>255) characters are utf8 encoded.</li>
+
+<li>Keys exceeding the maximum length for the underlying driver are digested - see <a href="#max_key_length" class="podlinkpod"
+>"max_key_length"</a> and <a href="#key_digester" class="podlinkpod"
+>"key_digester"</a>.</li>
+
+<li>For some drivers (e.g. <a href="http://search.cpan.org/perldoc?File" class="podlinkpod"
+>CHI::Driver::File</a>), keys containing special characters or whitespace are escaped with URL-like escaping.</li>
+</ul>
+
+<p>Note: All transformations above with the exception of escaping are <i>one-way</i>, meaning that CHI does not attempt to undo them when returned from <a href="#get_keys" class="podlinkpod"
+>"get_keys"</a>; and <i>idempotent</i>, meaning that applying them a second time has no effect. So when you call <a href="#get_keys" class="podlinkpod"
+>"get_keys"</a>, the key you get may not be exactly what you passed in, but you'll be able to pass that key in to get the corresponding object.</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Value_transformations"
+>Value transformations</a></h2>
+
+<ul>
+<li>Values which are references are automatically serialized before storing, and deserialized after retrieving - see <a href="#serializer" class="podlinkpod"
+>"serializer"</a>.</li>
+
+<li>Values with their utf8 flag on are utf8 encoded before storing, and utf8 decoded after retrieving.</li>
+</ul>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SUBCACHES"
+>SUBCACHES</a></h1>
+
+<p>It is possible to a cache to have one or more <i>subcaches</i>. There are currently two types of subcaches: <i>L1</i> and <i>mirror</i>.</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="L1_cache"
+>L1 cache</a></h2>
+
+<p>An L1 (or "level one") cache sits in front of the primary cache, usually to provide faster access for commonly accessed cache entries. For example, this places an in-process Memory cache in front of a Memcached cache:</p>
+
+<pre> my $cache = CHI->new(
+ driver => 'Memcached',
+ servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
+ l1_cache => { driver => 'Memory' }
+ );</pre>
+
+<p>On a <code>get</code>, the L1 cache is checked first - if a valid value exists, it is returned. Otherwise, the primary cache is checked - if a valid value exists, it is returned, and the value is placed in the L1 cache with the same expiration time. In this way, items fetched most frequently from the primary cache will tend to be in the L1 cache.</p>
+
+<p><code>set</code> operations are distributed to both the primary and L1 cache.</p>
+
+<p>You can access the L1 cache with the <code>l1_cache</code> method. For example, this clears the L1 cache but leaves the primary cache intact:</p>
+
+<pre> $cache->l1_cache->clear();</pre>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Mirror_cache"
+>Mirror cache</a></h2>
+
+<p>A mirror cache is a write-only cache that, over time, mirrors the content of the primary cache. <code>set</code> operations are distributed to both the primary and mirror cache, but <code>get</code> operations go only to the primary cache.</p>
+
+<p>Mirror caches are useful when you want to migrate from one cache to another. You can populate a mirror cache and switch over to it once it is sufficiently populated. For example, here we migrate from an old to a new cache directory:</p>
+
+<pre> my $cache = CHI->new(
+ driver => 'File',
+ root_dir => '/old/cache/root',
+ mirror_cache => { driver => 'File', root_dir => '/new/cache/root' },
+ );</pre>
+
+<p>We leave this running for a few hours (or as needed), then replace it with</p>
+
+<pre> my $cache = CHI->new(
+ driver => 'File',
+ root_dir => '/new/cache/root'
+ );</pre>
+
+<p>You can access the mirror cache with the <code>mirror_cache</code> method. For example, to see how many keys have made it over to the mirror cache:</p>
+
+<pre> my @keys = $cache->mirror_cache->get_keys();</pre>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Creating_subcaches"
+>Creating subcaches</a></h2>
+
+<p>As illustrated above, you create subcaches by passing the <code>l1_cache</code> and/or <code>mirror_cache</code> option to the CHI constructor. These options, in turn, should contain a hash of options to create the subcache with.</p>
+
+<p>The cache containing the subcache is called the <i>parent cache</i>.</p>
+
+<p>The following options are automatically inherited by the subcache from the parent cache, and may not be overriden:</p>
+
+<pre> expires_at
+ expires_in
+ expires_variance
+ serializer</pre>
+
+<p>(Reason: for efficiency, we want to create a single <a href="http://search.cpan.org/perldoc?CHI%3A%3ACacheObject" class="podlinkpod"
+>cache object</a> and store it in both caches. The cache object contains expiration information and is dependent on the serializer. At some point we could conceivably add code that will use a single object or separate objects as necessary, and thus allow the above to be overriden.)</p>
+
+<p>The following options are automatically inherited by the subcache from the parent cache, but may be overriden:</p>
+
+<pre> namespace
+ on_get_error
+ on_set_error</pre>
+
+<p>All other options are initialized in the subcache as normal, irrespective of their values in the parent.</p>
+
+<p>It is not currently possible to pass an existing cache in as a subcache.</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Common_subcache_behaviors"
+>Common subcache behaviors</a></h2>
+
+<p>These behaviors hold regardless of the type of subcache.</p>
+
+<p>The following methods are distributed to both the primary cache and subcache:</p>
+
+<pre> clear
+ expire
+ purge
+ remove</pre>
+
+<p>The following methods return information solely from the primary cache. However, you are free to call them explicitly on the subcache. (Trying to merge in subcache information automatically would require too much guessing about the caller's intent.)</p>
+
+<pre> get_keys
+ get_namespaces
+ get_object
+ get_expires_at
+ exists_and_is_expired
+ is_valid
+ dump_as_hash</pre>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Multiple_subcaches"
+>Multiple subcaches</a></h2>
+
+<p>It is valid for a cache to have one of each kind of subcache, e.g. an L1 cache and a mirror cache.</p>
+
+<p>A cache cannot have more than one of each kind of subcache, but a subcache can have its own subcaches, and so on. e.g.</p>
+
+<pre> my $cache = CHI->new(
+ driver => 'Memcached',
+ servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
+ l1_cache => {
+ driver => 'File',
+ root_dir => '/path/to/root',
+ l1_cache => { driver => 'Memory' }
+ }
+ );</pre>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Methods_for_parent_caches"
+>Methods for parent caches</a></h2>
+
+<dl>
+<dt><a name="has_subcaches(_)"
+>has_subcaches( )</a></dt>
+
+<dd>
+<p>Returns a boolean indicating whether this cache has subcaches.</p>
+
+<dt><a name="l1_cache(_)"
+>l1_cache( )</a></dt>
+
+<dd>
+<p>Returns the L1 cache for this cache, if any. Can only be called if <i>has_subcaches</i> is true.</p>
+
+<dt><a name="mirror_cache(_)"
+>mirror_cache( )</a></dt>
+
+<dd>
+<p>Returns the mirror cache for this cache, if any. Can only be called if <i>has_subcaches</i> is true.</p>
+
+<dt><a name="subcaches(_)"
+>subcaches( )</a></dt>
+
+<dd>
+<p>Returns the subcaches for this cache, in arbitrary order. Can only be called if <i>has_subcaches</i> is true.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Methods_for_subcaches"
+>Methods for subcaches</a></h2>
+
+<dl>
+<dt><a name="is_subcache(_)"
+>is_subcache( )</a></dt>
+
+<dd>
+<p>Returns a boolean indicating whether this is a subcache.</p>
+
+<dt><a name="subcache_type(_)"
+>subcache_type( )</a></dt>
+
+<dd>
+<p>Returns the type of subcache as a string, e.g. 'l1_cache' or 'mirror_cache'. Can only be called if <i>is_subcache</i> is true.</p>
+
+<dt><a name="parent_cache(_)"
+>parent_cache( )</a></dt>
+
+<dd>
+<p>Returns the parent cache (weakened to prevent circular reference). Can only be called if <i>is_subcache</i> is true.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Developing_new_kinds_of_subcaches"
+>Developing new kinds of subcaches</a></h2>
+
+<p>At this time, subcache behavior is hardcoded into CHI::Driver, so there is no easy way to modify the behavior of existing subcache types or create new ones. We'd like to make this more flexible eventually.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SIZE_AWARENESS"
+>SIZE AWARENESS</a></h1>
+
+<p>If <a href="#is_size_aware" class="podlinkpod"
+>"is_size_aware"</a> or <a href="#max_size" class="podlinkpod"
+>"max_size"</a> are passed to the constructor, the cache will be <i>size aware</i> - that is, it will keep track of its own size (in bytes) as items are added and removed. You can get a cache's size with <a href="#get_size" class="podlinkpod"
+>"get_size"</a>.</p>
+
+<p>Size aware caches generally keep track of their size in a separate meta-key, and have to do an extra store whenever the size changes (e.g. on each set and remove).</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Maximum_size_and_discard_policies"
+>Maximum size and discard policies</a></h2>
+
+<p>If a cache's size rises above its <a href="#max_size" class="podlinkpod"
+>"max_size"</a>, items are discarded until the cache size is sufficiently below the max size. (See <a href="#max_size_reduction_factor" class="podlinkpod"
+>"max_size_reduction_factor"</a> for how to fine-tune this.)</p>
+
+<p>The order in which items are discarded is controlled with <a href="#discard_policy" class="podlinkpod"
+>"discard_policy"</a>. The default discard policy is 'arbitrary', which discards items in an arbitrary order. The available policies and default policy can differ with each driver, e.g. the <a href="http://search.cpan.org/perldoc?Memory" class="podlinkpod"
+>CHI::Driver::Memory</a> driver provides and defaults to an 'LRU' policy.</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Appropriate_drivers"
+>Appropriate drivers</a></h2>
+
+<p>Size awareness was chiefly designed for, and works well with, the <a href="http://search.cpan.org/perldoc?Memory" class="podlinkpod"
+>CHI::Driver::Memory</a> driver: one often needs to enforce a maximum size on a memory cache, and the overhead of tracking size in memory is negligible. However, the capability may be useful with other drivers.</p>
+
+<p>Some drivers - for example, <a href="http://search.cpan.org/perldoc?FastMmap" class="podlinkpod"
+>CHI::Driver::FastMmap</a> and <a href="http://search.cpan.org/perldoc?Memcached" class="podlinkpod"
+>CHI::Driver::Memcached</a> - inherently keep track of their size and enforce a maximum size, and it makes no sense to turn on CHI's size awareness for these.</p>
+
+<p>Also, for drivers that cannot atomically read and update a value - for example, <a href="http://search.cpan.org/perldoc?File" class="podlinkpod"
+>CHI::Driver::File</a> - there is a race condition in the updating of size that can cause the size to grow inaccurate over time.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="AVAILABILITY_OF_DRIVERS"
+>AVAILABILITY OF DRIVERS</a></h1>
+
+<p>The following drivers are currently available as part of this distribution:</p>
+
+<ul>
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AMemory" class="podlinkpod"
+>CHI::Driver::Memory</a> - In-process memory based cache</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ARawMemory" class="podlinkpod"
+>CHI::Driver::RawMemory</a> - In-process memory based cache that stores references directly instead of deep-copying</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AFile" class="podlinkpod"
+>CHI::Driver::File</a> - File-based cache using one file per entry in a multi-level directory structure</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AFastMmap" class="podlinkpod"
+>CHI::Driver::FastMmap</a> - Shared memory interprocess cache via mmap'ed files</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ANull" class="podlinkpod"
+>CHI::Driver::Null</a> - Dummy cache in which nothing is stored</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ACacheCache" class="podlinkpod"
+>CHI::Driver::CacheCache</a> - CHI wrapper for Cache::Cache</li>
+</ul>
+
+<p>The following drivers are currently available as separate CPAN distributions:</p>
+
+<ul>
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3AMemcached" class="podlinkpod"
+>CHI::Driver::Memcached</a> - Distributed memory-based cache (works with <a href="http://search.cpan.org/perldoc?Cache%3A%3AMemcached" class="podlinkpod"
+>Cache::Memcached</a>, <a href="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast" class="podlinkpod"
+>Cache::Memcached::Fast</a>, and <a href="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3Alibmemcached" class="podlinkpod"
+>Cache::Memcached::libmemcached</a>)</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ADBI" class="podlinkpod"
+>CHI::Driver::DBI</a> - Cache in any DBI-supported database</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ABerkeleyDB" class="podlinkpod"
+>CHI::Driver::BerkeleyDB</a> - Cache in BerkeleyDB files</li>
+
+<li><a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ARedis" class="podlinkpod"
+>CHI::Driver::Redis</a> - Cache in <a href="http://redis.io/" class="podlinkurl"
+>Redis</a></li>
+</ul>
+
+<p>This list is likely incomplete. A complete set of drivers can be found on CPAN by searching for "CHI::Driver".</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="PERFORMANCE_COMPARISON_OF_DRIVERS"
+>PERFORMANCE COMPARISON OF DRIVERS</a></h1>
+
+<p>See <a href="http://search.cpan.org/perldoc?CHI%3A%3ABenchmarks" class="podlinkpod"
+>CHI::Benchmarks</a> for a comparison of read/write times of both CHI and non-CHI cache implementations.</p>
+
+<p><code>etc/bench/bench.pl</code> in the <code>CHI</code> distribution contains a script to run these types of benchmarks on your own system.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="DEVELOPING_NEW_DRIVERS"
+>DEVELOPING NEW DRIVERS</a></h1>
+
+<p>See <a href="http://search.cpan.org/perldoc?CHI%3A%3ADriver%3A%3ADevelopment" class="podlinkpod"
+>CHI::Driver::Development</a> for information on developing new drivers.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="LOGGING"
+>LOGGING</a></h1>
+
+<p><code>CHI</code> uses <a href="http://search.cpan.org/perldoc?Log%3A%3AAny" class="podlinkpod"
+>Log::Any</a> for logging events. For example, a debug log message is sent for every cache get and set.</p>
+
+<p>See <a href="http://search.cpan.org/perldoc?Log%3A%3AAny" class="podlinkpod"
+>Log::Any</a> documentation for how to control where logs get sent, if anywhere.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="STATS"
+>STATS</a></h1>
+
+<p>CHI can record statistics, such as number of hits, misses and sets, on a per-namespace basis and log the results to your <a href="http://search.cpan.org/perldoc?Log%3A%3AAny" class="podlinkpod"
+>Log::Any</a> logger. You can then use utilities included with this distribution to read stats back from the logs and report a summary. See <a href="http://search.cpan.org/perldoc?CHI%3A%3AStats" class="podlinkpod"
+>CHI::Stats</a> for details.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="RELATION_TO_OTHER_MODULES"
+>RELATION TO OTHER MODULES</a></h1>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Cache::Cache"
+>Cache::Cache</a></h2>
+
+<p>CHI is intended as an evolution of DeWitt Clinton's <a href="http://search.cpan.org/perldoc?Cache%3A%3ACache" class="podlinkpod"
+>Cache::Cache</a> package. It starts with the same basic API (which has proven durable over time) but addresses some implementation shortcomings that cannot be fixed in Cache::Cache due to backward compatibility concerns. In particular:</p>
+
+<dl>
+<dt><a name="Performance"
+>Performance</a></dt>
+
+<dd>
+<p>Some of Cache::Cache's subclasses (e.g. <a href="http://search.cpan.org/perldoc?Cache%3A%3AFileCache" class="podlinkpod"
+>Cache::FileCache</a>) have been justifiably criticized as inefficient. CHI has been designed from the ground up with performance in mind, both in terms of general overhead and in the built-in driver classes. Method calls are kept to a minimum, data is only serialized when necessary, and metadata such as expiration time is stored in packed binary format alongside the data.</p>
+
+<p>As an example, using Rob Mueller's cacheperl benchmarks, CHI's file driver runs 3 to 4 times faster than Cache::FileCache.</p>
+
+<dt><a name="Ease_of_subclassing"
+>Ease of subclassing</a></dt>
+
+<dd>
+<p>New Cache::Cache subclasses can be tedious to create, due to a lack of code refactoring, the use of non-OO package subroutines, and the separation of "cache" and "backend" classes. With CHI, the goal is to make the creation of new drivers as easy as possible, roughly the same as writing a TIE interface to your data store. Concerns like serialization and expiration options are handled by the driver base class so that individual drivers don't have to worry about them.</p>
+
+<dt><a name="Increased_compatibility_with_cache_implementations"
+>Increased compatibility with cache implementations</a></dt>
+
+<dd>
+<p>Probably because of the reasons above, Cache::Cache subclasses were never created for some of the most popular caches available on CPAN, e.g. <a href="http://search.cpan.org/perldoc?Cache%3A%3AFastMmap" class="podlinkpod"
+>Cache::FastMmap</a> and <a href="http://search.cpan.org/perldoc?Cache%3A%3AMemcached" class="podlinkpod"
+>Cache::Memcached</a>. CHI's goal is to be able to support these and other caches with a minimum performance overhead and minimum of glue code required.</p>
+</dd>
+</dl>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Cache"
+>Cache</a></h2>
+
+<p>The <a href="http://search.cpan.org/perldoc?Cache" class="podlinkpod"
+>Cache</a> distribution is another redesign and implementation of Cache, created by Chris Leishman in 2003. Like CHI, it improves performance and reduces the barrier to implementing new cache drivers. It breaks with the Cache::Cache interface in a few ways that I considered non-negotiable - for example, get/set do not serialize data, and namespaces are an optional feature that drivers may decide not to implement.</p>
+
+<h2><a class='u' href='#___top' title='click to go to top of document'
+name="Cache::Memcached,_Cache::FastMmap,_etc."
+>Cache::Memcached, Cache::FastMmap, etc.</a></h2>
+
+<p>CPAN sports a variety of full-featured standalone cache modules representing particular backends. CHI does not reinvent these but simply wraps them with an appropriate driver. For example, CHI::Driver::Memcached and CHI::Driver::FastMmap are thin layers around Cache::Memcached and Cache::FastMmap.</p>
+
+<p>Of course, because these modules already work on their own, there will be some overlap. Cache::FastMmap, for example, already has code to serialize data and handle expiration times. Here's how CHI resolves these overlaps.</p>
+
+<dl>
+<dt><a name="Serialization"
+>Serialization</a></dt>
+
+<dd>
+<p>CHI handles its own serialization, passing a flat binary string to the underlying cache backend.</p>
+
+<dt><a name="Expiration"
+>Expiration</a></dt>
+
+<dd>
+<p>CHI packs expiration times (as well as other metadata) inside the binary string passed to the underlying cache backend. The backend is unaware of these values; from its point of view the item has no expiration time. Among other things, this means that you can use CHI to examine expired items (e.g. with $cache->get_object) even if this is not supported natively by the backend.</p>
+
+<p>At some point CHI will provide the option of explicitly notifying the backend of the expiration time as well. This might allow the backend to do better storage management, etc., but would prevent CHI from examining expired items.</p>
+</dd>
+</dl>
+
+<p>Naturally, using CHI's FastMmap or Memcached driver will never be as time or storage efficient as simply using Cache::FastMmap or Cache::Memcached. In terms of performance, we've attempted to make the overhead as small as possible, on the order of 5% per get or set (benchmarks coming soon). In terms of storage size, CHI adds about 16 bytes of metadata overhead to each item. How much this matters obviously depends on the typical size of items in your cache.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SUPPORT_AND_DOCUMENTATION"
+>SUPPORT AND DOCUMENTATION</a></h1>
+
+<p>Questions and feedback are welcome, and should be directed to the perl-cache mailing list:</p>
+
+<pre> http://groups.google.com/group/perl-cache-discuss</pre>
+
+<p>Bugs and feature requests will be tracked at RT:</p>
+
+<pre> http://rt.cpan.org/NoAuth/Bugs.html?Dist=CHI
+ bug-chi@rt.cpan.org</pre>
+
+<p>The latest source code can be browsed and fetched at:</p>
+
+<pre> http://github.com/jonswar/perl-chi/tree/master
+ git clone git://github.com/jonswar/perl-chi.git</pre>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="TODO"
+>TODO</a></h1>
+
+<ul>
+<li>Perform cache benchmarks comparing both CHI and non-CHI cache implementations</li>
+
+<li>Release BerkeleyDB drivers as separate CPAN distributions</li>
+
+<li>Add docs comparing various strategies for reducing miss stampedes and cost of recomputes</li>
+
+<li>Add expires_next syntax (e.g. expires_next => 'hour')</li>
+
+<li>Support automatic serialization and escaping of keys</li>
+
+<li>Create XS versions of main functions in Driver.pm (e.g. get, set)</li>
+</ul>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="ACKNOWLEDGMENTS"
+>ACKNOWLEDGMENTS</a></h1>
+
+<p>Thanks to Dewitt Clinton for the original Cache::Cache, to Rob Mueller for the Perl cache benchmarks, and to Perrin Harkins for the discussions that got this going.</p>
+
+<p>CHI was originally designed and developed for the Digital Media group of the Hearst Corporation, a diversified media company based in New York City. Many thanks to Hearst management for agreeing to this open source release.</p>
+
+<h1><a class='u' href='#___top' title='click to go to top of document'
+name="SEE_ALSO"
+>SEE ALSO</a></h1>
+
+<p><a href="http://search.cpan.org/perldoc?Cache%3A%3ACache" class="podlinkpod"
+>Cache::Cache</a></p>
+
+<!-- end doc -->
+
+</body></html>
@@ -0,0 +1,58 @@
+
+
+__END__
+=pod
+
+=head1 NAME
+
+CHI::Benchmarks - Benchmarks of CHI and non-CHI drivers
+
+=head1 VERSION
+
+version 0.41
+
+=head1 DESCRIPTION
+
+These benchmarks were created with the script C<etc/bench/bench.pl> in this
+distribution.
+
+For each cache: 9510 gets, 490 sets, 10000 total operations.
+
+OS X v10.6.6, 2.2 GHz Intel Core 2 Duo, Perl 5.12.2.
+
+ Cache Get time Set time Run time Description
+ cache_ref 0.01ms 0.01ms 0.09s Cache::Ref
+ chi_memory_raw 0.02ms 0.04ms 0.19s CHI::Driver::MemoryRaw
+ cache_fastmmap 0.02ms 0.05ms 0.23s Cache::FastMmap
+ chi_memory 0.04ms 0.07ms 0.42s CHI::Driver::Memory
+ chi_berkeleydb 0.05ms 0.13ms 0.53s CHI::Driver::BerkeleyDB
+ chi_fastmmap 0.06ms 0.09ms 0.59s CHI::Driver::FastMmap
+ cache_cache_memory 0.07ms 0.08ms 0.69s Cache::MemoryCache
+ cache_memcached_fast 0.09ms 0.13ms 0.91s Cache::Memcached::Fast
+ cache_memcached_lib 0.10ms 0.13ms 1.02s Cache::Memcached::libmemcached
+ chi_memcached_lib 0.14ms 0.19ms 1.44s CHI::Driver::Memcached::libmemcached
+ chi_memcached_fast 0.15ms 0.20ms 1.49s CHI::Driver::Memcached::Fast
+ chi_file 0.14ms 0.81ms 1.73s CHI::Driver::File
+ chi_dbi_sqlite 0.13ms 1.62ms 1.99s CHI::Driver::DBI (sqlite)
+ chi_dbi_mysql 0.22ms 0.28ms 2.20s CHI::Driver::DBI (mysql)
+ cache_memcached_std 0.24ms 0.19ms 2.34s Cache::Memcached
+ chi_memcached_std 0.28ms 0.25ms 2.78s CHI::Driver::Memcached
+ cache_cache_file 0.46ms 1.35ms 5.05s Cache::FileCache
+
+=head1 SEE ALSO
+
+L<CHI|CHI>
+
+=head1 AUTHOR
+
+Jonathan Swartz <swartz@pobox.com>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2011 by Jonathan Swartz.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
+
@@ -1,6 +1,6 @@
package CHI::CacheObject;
BEGIN {
- $CHI::CacheObject::VERSION = '0.40';
+ $CHI::CacheObject::VERSION = '0.41';
}
use CHI::Constants qw(CHI_Max_Time);
use Encode;
@@ -17,6 +17,7 @@ use constant f_is_transformed => 6;
use constant f_cache_version => 7;
use constant f_value => 8;
use constant f_packed_data => 9;
+use constant f_size => 10;
use constant T_SERIALIZED => 1;
use constant T_UTF8_ENCODED => 2;
@@ -33,7 +34,7 @@ sub early_expires_at { $_[0]->[f_early_expires_at] }
sub expires_at { $_[0]->[f_expires_at] }
sub serializer { $_[0]->[f_serializer] }
sub _is_transformed { $_[0]->[f_is_transformed] }
-sub size { length( $_[0]->[f_raw_value] ) + $Metadata_Length }
+sub size { $_[0]->[f_size] }
sub set_early_expires_at {
$_[0]->[f_early_expires_at] = $_[1];
@@ -45,6 +46,8 @@ sub set_expires_at {
undef $_[0]->[f_packed_data];
}
+sub serialize_and_encode { 1 }
+
## no critic (ProhibitManyArgs)
sub new {
my ( $class, $key, $value, $created_at, $early_expires_at, $expires_at,
@@ -56,13 +59,20 @@ sub new {
#
my $is_transformed = 0;
my $raw_value = $value;
- if ( ref($raw_value) ) {
- $raw_value = $serializer->serialize($raw_value);
- $is_transformed = T_SERIALIZED;
+ my $size;
+ if ($serializer) {
+ if ( ref($raw_value) ) {
+ $raw_value = $serializer->serialize($raw_value);
+ $is_transformed = T_SERIALIZED;
+ }
+ elsif ( Encode::is_utf8($raw_value) ) {
+ $raw_value = Encode::encode( utf8 => $raw_value );
+ $is_transformed = T_UTF8_ENCODED;
+ }
+ $size = length($raw_value) + $Metadata_Length;
}
- elsif ( Encode::is_utf8($raw_value) ) {
- $raw_value = Encode::encode( utf8 => $raw_value );
- $is_transformed = T_UTF8_ENCODED;
+ else {
+ $size = 1;
}
# Not sure where this should be set and checked
@@ -70,15 +80,16 @@ sub new {
my $cache_version = 1;
return bless [
- $key, $raw_value, $serializer,
- $created_at, $early_expires_at, $expires_at,
- $is_transformed, $cache_version, $value,
+ $key, $raw_value, $serializer, $created_at,
+ $early_expires_at, $expires_at, $is_transformed, $cache_version,
+ $value, undef, $size
], $class;
}
sub unpack_from_data {
my ( $class, $key, $data, $serializer ) = @_;
+ return $data if !$serializer;
my $metadata = substr( $data, 0, $Metadata_Length );
my $raw_value = substr( $data, $Metadata_Length );
my $obj = bless [
@@ -87,12 +98,14 @@ sub unpack_from_data {
],
$class;
$obj->[f_packed_data] = $data;
+ $obj->[f_size] = length($data);
return $obj;
}
sub pack_to_data {
my ($self) = @_;
+ return $self if !$self->serializer;
if ( !defined( $self->[f_packed_data] ) ) {
my $data = pack( $Metadata_Format,
( @{$self} )[ f_created_at .. f_cache_version ] )
@@ -156,7 +169,7 @@ CHI::CacheObject - Contains information about cache entries
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -1,6 +1,6 @@
package CHI::Constants;
BEGIN {
- $CHI::Constants::VERSION = '0.40';
+ $CHI::Constants::VERSION = '0.41';
}
use strict;
use warnings;
@@ -28,7 +28,7 @@ CHI::Constants - Internal constants
=head1 VERSION
-version 0.40
+version 0.41
=head1 DESCRIPTION
@@ -1,6 +1,6 @@
package CHI::Driver::Base::CacheContainer;
BEGIN {
- $CHI::Driver::Base::CacheContainer::VERSION = '0.40';
+ $CHI::Driver::Base::CacheContainer::VERSION = '0.41';
}
use Moose;
use Moose::Util::TypeConstraints;
@@ -62,7 +62,7 @@ CHI::Driver::Base::CacheContainer - Caches that delegate to a contained cache
=head1 VERSION
-version 0.40
+version 0.41
=head1 DESCRIPTION
@@ -1,6 +1,6 @@
package CHI::Driver::CacheCache;
BEGIN {
- $CHI::Driver::CacheCache::VERSION = '0.40';
+ $CHI::Driver::CacheCache::VERSION = '0.41';
}
use Cache::Cache;
use Carp;
@@ -47,7 +47,7 @@ CHI::Driver::CacheCache - CHI wrapper for Cache::Cache
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -9,7 +9,7 @@ CHI::Driver::Development -- Manual for developing new CHI drivers
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -1,6 +1,6 @@
package CHI::Driver::FastMmap;
BEGIN {
- $CHI::Driver::FastMmap::VERSION = '0.40';
+ $CHI::Driver::FastMmap::VERSION = '0.41';
}
use Carp;
use Cache::FastMmap;
@@ -89,7 +89,7 @@ CHI::Driver::FastMmap - Shared memory interprocess cache via mmap'ed files
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -1,6 +1,6 @@
package CHI::Driver::File;
BEGIN {
- $CHI::Driver::File::VERSION = '0.40';
+ $CHI::Driver::File::VERSION = '0.41';
}
use Carp;
use Cwd qw(realpath cwd);
@@ -247,7 +247,7 @@ directory structure
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -1,6 +1,6 @@
package CHI::Driver::Memory;
BEGIN {
- $CHI::Driver::Memory::VERSION = '0.40';
+ $CHI::Driver::Memory::VERSION = '0.41';
}
use Carp qw(cluck croak);
use CHI::Constants qw(CHI_Meta_Namespace);
@@ -105,7 +105,7 @@ CHI::Driver::Memory - In-process memory based cache
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -122,9 +122,11 @@ This cache driver stores data on a per-process basis. This is the fastest of
the cache implementations, but data can not be shared between processes. Data
will remain in the cache until cleared, expired, or the process dies.
-To maintain the same semantics as other caches, data structures are deep-copied
-on set and get. Thus, modifications to the original data structure will not
-affect the data structure stored in the cache, and vica versa.
+To maintain the same semantics as other caches, references to data structures
+are deep-copied on set and get. Thus, modifications to the original data
+structure will not affect the data structure stored in the cache, and vica
+versa. See L<CHI::Driver::RawMemory> for a faster memory cache that sacrifices
+this behavior.
=head1 CONSTRUCTOR OPTIONS
@@ -158,7 +160,7 @@ policy.
=head1 SEE ALSO
-L<CHI|CHI>
+L<CHI::Driver::RawMemory>, L<CHI>
=head1 AUTHOR
@@ -1,6 +1,6 @@
package CHI::Driver::Metacache;
BEGIN {
- $CHI::Driver::Metacache::VERSION = '0.40';
+ $CHI::Driver::Metacache::VERSION = '0.41';
}
use CHI::Constants qw(CHI_Meta_Namespace);
use Moose;
@@ -66,7 +66,7 @@ CHI::Driver::Metacache - Metacache for internal CHI use
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -1,6 +1,6 @@
package CHI::Driver::Null;
BEGIN {
- $CHI::Driver::Null::VERSION = '0.40';
+ $CHI::Driver::Null::VERSION = '0.41';
}
use Moose;
use strict;
@@ -28,7 +28,7 @@ CHI::Driver::Null - Nothing is cached
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -0,0 +1,93 @@
+package CHI::Driver::RawMemory;
+BEGIN {
+ $CHI::Driver::RawMemory::VERSION = '0.41';
+}
+use Moose;
+use strict;
+use warnings;
+
+extends 'CHI::Driver::Memory';
+
+has 'serializer' => ( is => 'ro', default => undef, init_arg => undef );
+
+__PACKAGE__->meta->make_immutable();
+
+1;
+
+
+
+=pod
+
+=head1 NAME
+
+CHI::Driver::RawMemory - In-process memory cache that stores direct references
+
+=head1 VERSION
+
+version 0.41
+
+=head1 SYNOPSIS
+
+ use CHI;
+
+ my $hash = {};
+ my $cache = CHI->new( driver => 'RawMemory', datastore => $hash );
+
+ my $cache = CHI->new( driver => 'RawMemory', global => 1 );
+
+=head1 DESCRIPTION
+
+This is a subclass of L<CHI::Driver::Memory|CHI::Driver::Memory> that stores
+references to data structures directly instead of serializing / deserializing.
+This makes the cache faster at getting and setting complex data structures, but
+unlike most drivers, modifications to the original data structure I<will>
+affect the data structure stored in the cache, and vica versa. e.g.
+
+ my $cache = CHI->new( driver => 'Memory', global => 1 );
+ my $lst = ['foo'];
+ $cache->set('key' => $lst); # serializes $lst before storing
+ $cache->get('key'); # returns ['foo']
+ $lst->[0] = 'bar';
+ $cache->get('key'); # returns ['foo']
+
+ my $cache = CHI->new( driver => 'RawMemory', global => 1 );
+ my $lst = ['foo'];
+ $cache->set('key' => $lst); # stores $lst directly
+ $cache->get('key'); # returns ['foo']
+ $lst->[0] = 'bar';
+ $cache->get('key'); # returns ['bar']!
+
+=head1 CONSTRUCTOR OPTIONS
+
+Same as L<CHI::Driver::Memory|CHI::Driver::Memory>.
+
+=head1 SIZE AWARENESS
+
+For the purpose of L<size-awareness|CHI/SIZE AWARENESS>, all items count as
+size 1 for this driver. (Because data structures are not serialized, there's no
+good way to determine their size.)
+
+ # Keep a maximum of 10 items in cache
+ #
+ my $cache = CHI->new( driver => 'RawMemory', datastore => {}, max_size => 10 );
+
+=head1 SEE ALSO
+
+L<CHI::Driver::Memory>, L<CHI>
+
+=head1 AUTHOR
+
+Jonathan Swartz <swartz@pobox.com>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2011 by Jonathan Swartz.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
+
+
+__END__
+
@@ -1,6 +1,6 @@
package CHI::Driver::Role::HasSubcaches;
BEGIN {
- $CHI::Driver::Role::HasSubcaches::VERSION = '0.40';
+ $CHI::Driver::Role::HasSubcaches::VERSION = '0.41';
}
use Moose::Role;
use Hash::MoreUtils qw(slice_exists);
@@ -90,18 +90,24 @@ after 'set_object' => sub {
my $subcaches = $self->subcaches;
foreach my $subcache (@$subcaches) {
- $subcache->set_object( $key, $obj );
- $subcache->_log_set_result( $log, $obj )
- if $log->is_debug;
+ $subcache->set(
+ $key,
+ $obj->value,
+ {
+ expires_at => $obj->expires_at,
+ early_expires_at => $obj->early_expires_at
+ }
+ );
}
};
around 'get' => sub {
- my $orig = shift;
- my $self = shift;
+ my $orig = shift;
+ my $self = shift;
+ my ( $key, %params ) = @_;
my $l1_cache = $self->l1_cache;
- if ( !defined($l1_cache) ) {
+ if ( !defined($l1_cache) || $params{obj} ) {
return $self->$orig(@_);
}
else {
@@ -117,11 +123,17 @@ around 'get' => sub {
my $value = $self->$orig( $key, %params );
if ( defined($value) ) {
- # If found in primary cache, write back to l1 cache. Use same $obj,
- # meaning same metadata and serialization.
+ # If found in primary cache, write back to l1 cache.
#
my $obj = ${ $params{obj_ref} };
- $l1_cache->set_object( $key, $obj );
+ $l1_cache->set(
+ $key,
+ $obj->value,
+ {
+ expires_at => $obj->expires_at,
+ early_expires_at => $obj->early_expires_at
+ }
+ );
}
return $value;
}
@@ -1,16 +1,16 @@
package CHI::Driver::Role::IsSizeAware;
BEGIN {
- $CHI::Driver::Role::IsSizeAware::VERSION = '0.40';
+ $CHI::Driver::Role::IsSizeAware::VERSION = '0.41';
}
use Carp::Assert;
use Moose::Role;
use strict;
use warnings;
-has 'max_size' => ( is => 'rw', isa => 'CHI::Types::MemorySize', coerce => 1 );
-has 'max_size_reduction_factor' => ( is => 'rw', isa => 'Num', default => 0.8 );
has 'discard_policy' => ( is => 'ro', isa => 'Maybe[CHI::Types::DiscardPolicy]', builder => '_build_discard_policy' );
has 'discard_timeout' => ( is => 'rw', isa => 'Num', default => 10 );
+has 'max_size' => ( is => 'rw', isa => 'CHI::Types::MemorySize', coerce => 1 );
+has 'max_size_reduction_factor' => ( is => 'rw', isa => 'Num', default => 0.8 );
use constant Size_Key => 'CHI_IsSizeAware_size';
@@ -39,11 +39,11 @@ around 'remove' => sub {
my $self = shift;
my ($key) = @_;
- my ( $size_delta, $data );
+ my ( $size_delta, $obj );
if ( !$self->{_no_set_size_on_remove}
- && ( $data = $self->fetch($key) ) )
+ && ( $obj = $self->get_object($key) ) )
{
- $size_delta = -1 * length($data);
+ $size_delta = -1 * $obj->size;
}
$self->$orig(@_);
if ($size_delta) {
@@ -57,8 +57,8 @@ around 'set_object' => sub {
# If item exists, record its size so we can subtract it below
#
my $size_delta = 0;
- if ( my $data = $self->fetch($key) ) {
- $size_delta = -1 * length($data);
+ if ( my $obj = $self->get_object($key) ) {
+ $size_delta = -1 * $obj->size;
}
my $result = $self->$orig( $key, $obj );
@@ -119,9 +119,9 @@ sub discard_to_size {
while ( $size > $ceiling )
{
if ( defined( my $key = $discard_iterator->() ) ) {
- if ( my $data = $self->fetch($key) ) {
+ if ( my $obj = $self->get_object($key) ) {
$self->remove($key);
- $size -= length($data);
+ $size -= $obj->size;
}
}
else {
@@ -1,6 +1,6 @@
package CHI::Driver::Role::IsSubcache;
BEGIN {
- $CHI::Driver::Role::IsSubcache::VERSION = '0.40';
+ $CHI::Driver::Role::IsSubcache::VERSION = '0.41';
}
use Moose::Role;
use strict;
@@ -1,6 +1,6 @@
package CHI::Driver::Role::Universal;
BEGIN {
- $CHI::Driver::Role::Universal::VERSION = '0.40';
+ $CHI::Driver::Role::Universal::VERSION = '0.41';
}
use CHI::Constants qw(CHI_Meta_Namespace);
use Moose::Role;
@@ -1,6 +1,6 @@
package CHI::Driver;
BEGIN {
- $CHI::Driver::VERSION = '0.40';
+ $CHI::Driver::VERSION = '0.41';
}
use Carp;
use CHI::CacheObject;
@@ -83,6 +83,8 @@ sub declare_unsupported_methods {
}
}
+sub cache_object_class { 'CHI::CacheObject' }
+
# To override time() for testing - must be writable in a dynamically scoped way from tests
our $Test_Time; ## no critic (ProhibitPackageVars)
our $Build_Depth = 0; ## no critic (ProhibitPackageVars)
@@ -145,28 +147,22 @@ sub get {
my ( $self, $key, %params ) = @_;
croak "must specify key" unless defined($key);
- $key = $self->transform_key($key);
my $ns_stats = $self->{ns_stats};
# Fetch cache object
#
- my $data = $params{data};
- if ( !defined $data ) {
- $data = eval { $self->fetch($key) };
- if ( my $error = $@ ) {
- $ns_stats->{'get_errors'}++ if defined($ns_stats);
- $self->_handle_get_error( $error, $key );
- return undef;
- }
+ my $obj = eval { $params{obj} || $self->get_object($key) };
+ if ( my $error = $@ ) {
+ $ns_stats->{'get_errors'}++ if defined($ns_stats);
+ $self->_handle_get_error( $error, $key );
+ return undef;
}
-
- if ( !defined $data ) {
+ if ( !defined $obj ) {
$ns_stats->{'absent_misses'}++ if defined($ns_stats);
$self->_log_get_result( $log, "MISS (not in cache)", $key )
if $log->is_debug;
return undef;
}
- my $obj = $self->unpack_from_data( $key, $data );
if ( defined( my $obj_ref = $params{obj_ref} ) ) {
$$obj_ref = $obj;
}
@@ -202,7 +198,8 @@ sub get {
sub unpack_from_data {
my ( $self, $key, $data ) = @_;
- return CHI::CacheObject->unpack_from_data( $key, $data, $self->serializer );
+ return $self->cache_object_class->unpack_from_data( $key, $data,
+ $self->serializer );
}
sub get_object {
@@ -311,8 +308,8 @@ sub set_with_options {
# Pack into data, and store
#
my $obj =
- CHI::CacheObject->new( $key, $value, $created_at, $early_expires_at,
- $expires_at, $self->serializer );
+ $self->cache_object_class->new( $key, $value, $created_at,
+ $early_expires_at, $expires_at, $self->serializer );
if ( defined( my $obj_ref = $options->{obj_ref} ) ) {
$$obj_ref = $obj;
}
@@ -431,17 +428,31 @@ sub fetch_multi_hashref {
return { map { ( $_, $self->fetch($_) ) } @$keys };
}
+sub get_multi_hashref_objects {
+ my ( $self, $keys ) = @_;
+ my $key_data = $self->fetch_multi_hashref($keys);
+ return {
+ map {
+ my $data = $key_data->{$_};
+ defined($data)
+ ? ( $_, $self->unpack_from_data( $_, $data ) )
+ : ( $_, undef )
+ } keys(%$key_data)
+ };
+}
+
sub get_multi_arrayref {
my ( $self, $keys ) = @_;
croak "must specify keys" unless defined($keys);
my $transformed_keys = [ map { $self->transform_key($_) } @$keys ];
my $key_count = scalar(@$keys);
- my $keyvals = $self->fetch_multi_hashref($transformed_keys);
+ my $keyobjs = $self->get_multi_hashref_objects($transformed_keys);
return [
map {
- $self->get( $keys->[$_],
- data => $keyvals->{ $transformed_keys->[$_] } )
+ my $key = $transformed_keys->[$_];
+ my $obj = $keyobjs->{$key};
+ $obj ? $self->get( $key, obj => $obj ) : undef
} ( 0 .. $key_count - 1 )
];
}
@@ -630,7 +641,7 @@ CHI::Driver - Base class for all CHI drivers
=head1 VERSION
-version 0.40
+version 0.41
=head1 DESCRIPTION
@@ -3,7 +3,7 @@
#
package CHI::Serializer::JSON;
BEGIN {
- $CHI::Serializer::JSON::VERSION = '0.40';
+ $CHI::Serializer::JSON::VERSION = '0.41';
}
use Moose;
use JSON;
@@ -3,7 +3,7 @@
#
package CHI::Serializer::Storable;
BEGIN {
- $CHI::Serializer::Storable::VERSION = '0.40';
+ $CHI::Serializer::Storable::VERSION = '0.41';
}
use Moose;
use Storable;
@@ -1,6 +1,6 @@
package CHI::Stats;
BEGIN {
- $CHI::Stats::VERSION = '0.40';
+ $CHI::Stats::VERSION = '0.41';
}
use Log::Any qw($log);
use Moose;
@@ -137,7 +137,7 @@ CHI::Stats - Record and report per-namespace cache statistics
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -1,6 +1,6 @@
package CHI::Test::Class;
BEGIN {
- $CHI::Test::Class::VERSION = '0.40';
+ $CHI::Test::Class::VERSION = '0.41';
}
use Getopt::Long;
use CHI::Util qw(can_load);
@@ -1,6 +1,6 @@
package CHI::Test::Driver::NonMoose;
BEGIN {
- $CHI::Test::Driver::NonMoose::VERSION = '0.40';
+ $CHI::Test::Driver::NonMoose::VERSION = '0.41';
}
use Carp;
use strict;
@@ -1,6 +1,6 @@
package CHI::Test::Driver::Readonly;
BEGIN {
- $CHI::Test::Driver::Readonly::VERSION = '0.40';
+ $CHI::Test::Driver::Readonly::VERSION = '0.41';
}
use Carp;
use Moose;
@@ -1,6 +1,6 @@
package CHI::Test::Driver::Role::CheckKeyValidity;
BEGIN {
- $CHI::Test::Driver::Role::CheckKeyValidity::VERSION = '0.40';
+ $CHI::Test::Driver::Role::CheckKeyValidity::VERSION = '0.41';
}
use Carp;
use Moose::Role;
@@ -1,6 +1,6 @@
package CHI::Test::Driver::Writeonly;
BEGIN {
- $CHI::Test::Driver::Writeonly::VERSION = '0.40';
+ $CHI::Test::Driver::Writeonly::VERSION = '0.41';
}
use Carp;
use strict;
@@ -1,6 +1,6 @@
package CHI::Test::Util;
BEGIN {
- $CHI::Test::Util::VERSION = '0.40';
+ $CHI::Test::Util::VERSION = '0.41';
}
use Date::Parse;
use Test::Builder;
@@ -2,7 +2,7 @@
#
package CHI::Test;
BEGIN {
- $CHI::Test::VERSION = '0.40';
+ $CHI::Test::VERSION = '0.41';
}
use Log::Any::Test; # as early as possible
use List::MoreUtils qw(uniq);
@@ -1,6 +1,6 @@
package CHI::Types;
BEGIN {
- $CHI::Types::VERSION = '0.40';
+ $CHI::Types::VERSION = '0.41';
}
use Carp;
use CHI::Util qw(can_load parse_duration parse_memory_size);
@@ -1,6 +1,6 @@
package CHI::Util;
BEGIN {
- $CHI::Util::VERSION = '0.40';
+ $CHI::Util::VERSION = '0.41';
}
use Carp qw( croak longmess );
use Class::MOP;
@@ -1,6 +1,6 @@
package CHI::t::Bugs;
BEGIN {
- $CHI::t::Bugs::VERSION = '0.40';
+ $CHI::t::Bugs::VERSION = '0.41';
}
use strict;
use warnings;
@@ -10,11 +10,12 @@ use base qw(CHI::Test::Class);
# A place for testing obscure bug fixes. When possible, test will be named for RT ticket.
-sub test_48998 : Test(1) {
+sub test_48998 : Tests {
my $cache = CHI->new( driver => 'Memory', global => 1 );
$cache->set( 'a', 5 );
$cache->set( 'b', 6 );
eval { die "bleah" };
+ $DB::single = 1;
cmp_deeply( $cache->get_multi_arrayref( [ 'a', 'b' ] ),
[ 5, 6 ], "get_multi" );
}
@@ -1,31 +1,31 @@
package CHI::t::Constants;
BEGIN {
- $CHI::t::Constants::VERSION = '0.40';
+ $CHI::t::Constants::VERSION = '0.41';
}
use strict;
use warnings;
use CHI::Test;
use base qw(CHI::Test::Class);
-sub test_import : Test(4) {
+sub test_import : Tests {
{
package Foo;
BEGIN {
- $Foo::VERSION = '0.40';
+ $Foo::VERSION = '0.41';
}
use CHI::Constants qw(CHI_Meta_Namespace);
}
{
package Bar;
BEGIN {
- $Bar::VERSION = '0.40';
+ $Bar::VERSION = '0.41';
}
use CHI::Constants qw(:all);
}
{
package Baz;
BEGIN {
- $Baz::VERSION = '0.40';
+ $Baz::VERSION = '0.41';
}
}
is( Foo::CHI_Meta_Namespace, '_CHI_METACACHE' );
@@ -1,6 +1,6 @@
package CHI::t::Driver::CacheCache;
BEGIN {
- $CHI::t::Driver::CacheCache::VERSION = '0.40';
+ $CHI::t::Driver::CacheCache::VERSION = '0.41';
}
use strict;
use warnings;
@@ -1,6 +1,6 @@
package CHI::t::Driver::FastMmap;
BEGIN {
- $CHI::t::Driver::FastMmap::VERSION = '0.40';
+ $CHI::t::Driver::FastMmap::VERSION = '0.41';
}
use strict;
use warnings;
@@ -23,7 +23,7 @@ sub new_cache_options {
return ( $self->SUPER::new_cache_options(), root_dir => $root_dir );
}
-sub test_fm_cache : Test(4) {
+sub test_fm_cache : Tests {
my ($self) = @_;
# Create brand new cache and check defaults
@@ -44,7 +44,7 @@ sub test_fm_cache : Test(4) {
}
}
-sub test_parameter_passthrough : Test(2) {
+sub test_parameter_passthrough : Tests {
my ($self) = @_;
my $cache = $self->new_cache( cache_size => '500k' );
@@ -62,7 +62,7 @@ sub test_parameter_passthrough : Test(2) {
);
}
-sub test_value_too_large : Tests(2) {
+sub test_value_too_large : Tests {
my ($self) = @_;
my $cache = $self->new_cache(
@@ -1,6 +1,6 @@
package CHI::t::Driver::File::DepthZero;
BEGIN {
- $CHI::t::Driver::File::DepthZero::VERSION = '0.40';
+ $CHI::t::Driver::File::DepthZero::VERSION = '0.41';
}
use strict;
use warnings;
@@ -19,7 +19,7 @@ sub new_cache_options {
return ( $self->SUPER::new_cache_options(), depth => 0 );
}
-sub test_default_depth : Test(2) {
+sub test_default_depth : Tests {
my $self = shift;
my $cache = $self->new_cache();
@@ -1,6 +1,6 @@
package CHI::t::Driver::File;
BEGIN {
- $CHI::t::Driver::File::VERSION = '0.40';
+ $CHI::t::Driver::File::VERSION = '0.41';
}
use strict;
use warnings;
@@ -24,7 +24,7 @@ sub new_cache_options {
{
package CHI::t::Driver::File::NoTempDriver;
BEGIN {
- $CHI::t::Driver::File::NoTempDriver::VERSION = '0.40';
+ $CHI::t::Driver::File::NoTempDriver::VERSION = '0.41';
}
use Moose;
extends 'CHI::Driver::File';
@@ -39,7 +39,7 @@ BEGIN {
{
package CHI::t::Driver::File::BadTempDriver;
BEGIN {
- $CHI::t::Driver::File::BadTempDriver::VERSION = '0.40';
+ $CHI::t::Driver::File::BadTempDriver::VERSION = '0.41';
}
use Moose;
extends 'CHI::Driver::File';
@@ -53,7 +53,7 @@ BEGIN {
# Test that we can override how temporary files are generated
#
-sub test_generate_temporary_filename : Tests(3) {
+sub test_generate_temporary_filename : Tests {
my $self = shift;
$self->{cache} =
@@ -64,14 +64,14 @@ sub test_generate_temporary_filename : Tests(3) {
throws_ok { $self->test_simple() } qr/error during cache set/;
}
-sub test_default_depth : Test(1) {
+sub test_default_depth : Tests {
my $self = shift;
my $cache = $self->new_cache();
is( $cache->depth, 2 );
}
-sub test_creation_and_deletion : Test(7) {
+sub test_creation_and_deletion : Tests {
my $self = shift;
my $cache = $self->new_cache();
@@ -97,7 +97,7 @@ sub test_creation_and_deletion : Test(7) {
"namespace dir '$namespace_dir' does not exist after clear" );
}
-sub test_root_dir_does_not_exist : Test(4) {
+sub test_root_dir_does_not_exist : Tests {
my $self = shift;
my $parent_dir =
@@ -111,7 +111,7 @@ sub test_root_dir_does_not_exist : Test(4) {
ok( -d $non_existent_root, "$non_existent_root exists after set" );
}
-sub test_ignore_bad_namespaces : Tests(1) {
+sub test_ignore_bad_namespaces : Tests {
my $self = shift;
my $cache = $self->new_cleared_cache(
root_dir => tempdir( "chi-driver-file-XXXX", TMPDIR => 1, CLEANUP => 1 )
@@ -127,7 +127,7 @@ sub test_ignore_bad_namespaces : Tests(1) {
);
}
-sub test_default_discard : Tests(1) {
+sub test_default_discard : Tests {
my $self = shift;
my $cache = $self->new_cleared_cache( is_size_aware => 1 );
is( $cache->discard_policy, 'arbitrary' );
@@ -1,6 +1,6 @@
package CHI::t::Driver::Memory;
BEGIN {
- $CHI::t::Driver::Memory::VERSION = '0.40';
+ $CHI::t::Driver::Memory::VERSION = '0.41';
}
use strict;
use warnings;
@@ -37,7 +37,7 @@ sub new_cache {
return $cache;
}
-sub test_short_driver_name : Tests(1) {
+sub test_short_driver_name : Tests {
my ($self) = @_;
my $cache = $self->{cache};
@@ -46,7 +46,7 @@ sub test_short_driver_name : Tests(1) {
# Warn if global or datastore not passed, but still use global datastore by default
#
-sub test_global_or_datastore_required : Tests(3) {
+sub test_global_or_datastore_required : Tests {
my ( $cache, $cache2 );
warning_like( sub { $cache = CHI->new( driver => 'Memory' ) },
qr/must specify either/ );
@@ -58,7 +58,7 @@ sub test_global_or_datastore_required : Tests(3) {
# Make sure two caches don't share datastore
#
-sub test_different_datastores : Tests(1) {
+sub test_different_datastores : Tests {
my $self = shift;
my $cache1 = CHI->new( driver => 'Memory', datastore => {} );
my $cache2 = CHI->new( driver => 'Memory', datastore => {} );
@@ -91,7 +91,7 @@ sub test_clear_datastore : Tests {
}
}
-sub test_lru_discard : Tests(2) {
+sub test_lru_discard : Tests {
my $self = shift;
my $cache = $self->new_cleared_cache( max_size => 41 );
is( $cache->discard_policy, 'lru' );
@@ -1,6 +1,6 @@
package CHI::t::Driver::NonMoose;
BEGIN {
- $CHI::t::Driver::NonMoose::VERSION = '0.40';
+ $CHI::t::Driver::NonMoose::VERSION = '0.41';
}
use strict;
use warnings;
@@ -0,0 +1,120 @@
+package CHI::t::Driver::RawMemory;
+BEGIN {
+ $CHI::t::Driver::RawMemory::VERSION = '0.41';
+}
+use strict;
+use warnings;
+use CHI::Test;
+use CHI::Test::Util qw(is_between);
+use base qw(CHI::t::Driver::Memory);
+
+sub new_cache {
+ my $self = shift;
+ my %params = @_;
+
+ # If new_cache called with datastore, ignore global flag (otherwise would be an error)
+ #
+ if ( $params{datastore} ) {
+ $params{global} = 0;
+ }
+
+ my $cache = CHI->new( $self->new_cache_options(), %params );
+ return $cache;
+}
+
+# Not applicable to raw memory
+#
+sub test_deep_copy { }
+sub test_scalar_return_values { }
+sub test_serialize { }
+sub test_serializers { }
+
+# Would need tweaking to pass
+#
+sub test_custom_discard_policy { }
+sub test_lru_discard { }
+sub test_size_awareness_with_subcaches { }
+sub test_stats { }
+sub test_subcache_overridable_params { }
+
+# Size of all items = 1 in this driver
+#
+sub test_size_awareness : Tests {
+ my $self = shift;
+ my ( $key, $value ) = $self->kvpair();
+
+ ok( !$self->new_cleared_cache()->is_size_aware(),
+ "not size aware by default" );
+ ok( $self->new_cleared_cache( is_size_aware => 1 )->is_size_aware(),
+ "is_size_aware turns on size awareness" );
+ ok( $self->new_cleared_cache( max_size => 10 )->is_size_aware(),
+ "max_size turns on size awareness" );
+
+ my $cache = $self->new_cleared_cache( is_size_aware => 1 );
+ is( $cache->get_size(), 0, "size is 0 for empty" );
+ $cache->set( $key, $value );
+ is( $cache->get_size, 1, "size is 1 with one value" );
+ $cache->set( $key, scalar( $value x 5 ) );
+ is( $cache->get_size, 1, "size is still 1 after override" );
+ $cache->set( $key, scalar( $value x 5 ) );
+ is( $cache->get_size, 1, "size is still 1 after same overwrite" );
+ $cache->set( $key, scalar( $value x 2 ) );
+ is( $cache->get_size, 1, "size is 1 after overwrite" );
+ $cache->set( $key . "2", $value );
+ is( $cache->get_size, 2, "size is 2 after second key" );
+ $cache->remove($key);
+ is( $cache->get_size, 1, "size is 1 again after removing key" );
+ $cache->remove( $key . "2" );
+ is( $cache->get_size, 0, "size is 0 again after removing keys" );
+ $cache->set( $key, $value );
+ is( $cache->get_size, 1, "size is 1 with one value" );
+ $cache->clear();
+ is( $cache->get_size, 0, "size is 0 again after clear" );
+
+ my $time = time() + 10;
+ $cache->set( $key, $value, { expires_at => $time } );
+ is( $cache->get_expires_at($key),
+ $time, "set options respected by size aware cache" );
+}
+
+sub test_max_size : Tests {
+ my $self = shift;
+
+ my $cache = $self->new_cleared_cache( max_size => 5 );
+ ok( $cache->is_size_aware, "is size aware when max_size specified" );
+ my $value = 'x';
+
+ for ( my $i = 0 ; $i < 5 ; $i++ ) {
+ $cache->set( "key$i", $value );
+ }
+ for ( my $i = 0 ; $i < 10 ; $i++ ) {
+ $cache->set( "key" . int( rand(10) ), $value );
+ is_between( $cache->get_size, 3, 5,
+ "after iteration $i, size = " . $cache->get_size );
+ is_between( scalar( $cache->get_keys ),
+ 3, 5, "after iteration $i, keys = " . scalar( $cache->get_keys ) );
+ }
+}
+
+# Test that we're caching a reference, not a deep copy
+#
+sub test_cache_ref : Tests {
+ my $self = shift;
+ my $cache = $self->{cache};
+ my $lst = ['foo'];
+ $cache->set( 'key1' => $lst );
+ $cache->set( 'key2' => $lst );
+ is( $cache->get('key1'), $lst, "got same reference" );
+ is( $cache->get('key2'), $lst, "got same reference" );
+ $lst->[0] = 'bar';
+ is( $cache->get('key1')->[0], 'bar', "changed value in cache" );
+}
+
+sub test_short_driver_name : Tests {
+ my ($self) = @_;
+
+ my $cache = $self->{cache};
+ is( $cache->short_driver_name, 'RawMemory' );
+}
+
+1;
@@ -1,6 +1,6 @@
package CHI::t::Driver::Subcache::l1_cache;
BEGIN {
- $CHI::t::Driver::Subcache::l1_cache::VERSION = '0.40';
+ $CHI::t::Driver::Subcache::l1_cache::VERSION = '0.41';
}
use strict;
use warnings;
@@ -27,7 +27,7 @@ sub new_cache_options {
);
}
-sub test_stats : Test(3) {
+sub test_stats : Tests {
my $self = shift;
my $stats = $self->testing_chi_root_class->stats;
@@ -1,6 +1,6 @@
package CHI::t::Driver::Subcache::mirror_cache;
BEGIN {
- $CHI::t::Driver::Subcache::mirror_cache::VERSION = '0.40';
+ $CHI::t::Driver::Subcache::mirror_cache::VERSION = '0.41';
}
use strict;
use warnings;
@@ -1,6 +1,6 @@
package CHI::t::Driver::Subcache;
BEGIN {
- $CHI::t::Driver::Subcache::VERSION = '0.40';
+ $CHI::t::Driver::Subcache::VERSION = '0.41';
}
use strict;
use warnings;
@@ -21,15 +21,15 @@ sub set_standard_keys_and_values {
# Skip these tests - the logging will be wrong
#
-sub test_l1_cache : Tests(1) {
+sub test_l1_cache : Tests {
ok(1);
}
-sub test_mirror_cache : Tests(1) {
+sub test_mirror_cache : Tests {
ok(1);
}
-sub test_logging : Tests(1) {
+sub test_logging : Tests {
ok(1);
}
@@ -1,6 +1,6 @@
package CHI::t::Driver;
BEGIN {
- $CHI::t::Driver::VERSION = '0.40';
+ $CHI::t::Driver::VERSION = '0.41';
}
use strict;
use warnings;
@@ -150,7 +150,7 @@ sub set_some_keys {
}
}
-sub test_encode : Test(11) {
+sub test_encode : Tests {
my $self = shift;
my $cache = $self->new_cleared_cache();
@@ -205,7 +205,7 @@ sub test_encode : Test(11) {
is( $cache->get("binary"), $binary_off, "stored binary_on = binary_off" );
}
-sub test_simple : Test(2) {
+sub test_simple : Tests {
my $self = shift;
my $cache = shift || $self->{cache};
@@ -213,7 +213,7 @@ sub test_simple : Test(2) {
is( $cache->get( $self->{keys}->{medium} ), $self->{values}->{medium} );
}
-sub test_driver_class : Tests(3) {
+sub test_driver_class : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -271,7 +271,7 @@ sub test_key_types : Tests {
}
}
-sub test_deep_copy : Test(9) {
+sub test_deep_copy : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -299,7 +299,7 @@ sub test_deep_copy : Test(9) {
"altering original set structure does not affect cached copy" );
}
-sub test_expires_immediately : Test(32) {
+sub test_expires_immediately : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -327,7 +327,7 @@ sub test_expires_immediately : Test(32) {
$test_expires_immediately->("now");
}
-sub test_expires_shortly : Test(18) {
+sub test_expires_shortly : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -361,7 +361,7 @@ sub test_expires_shortly : Test(18) {
$test_expires_shortly->( { expires_at => time + 2 } );
}
-sub test_expires_later : Test(30) {
+sub test_expires_later : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -394,7 +394,7 @@ sub test_expires_later : Test(30) {
$test_expires_later->( { expires_at => time + 3600 } );
}
-sub test_expires_never : Test(6) {
+sub test_expires_never : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -415,7 +415,7 @@ sub test_expires_never : Test(6) {
$test_expires_never->('never');
}
-sub test_expires_defaults : Test(4) {
+sub test_expires_defaults : Tests {
my $self = shift;
my $start_time = time();
@@ -449,7 +449,7 @@ sub test_expires_defaults : Test(4) {
"after expires_at method" );
}
-sub test_expires_manually : Test(3) {
+sub test_expires_manually : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -462,7 +462,7 @@ sub test_expires_manually : Test(3) {
ok( !$cache->is_valid($key), "invalid after expire ($desc)" );
}
-sub test_expires_conditionally : Test(8) {
+sub test_expires_conditionally : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -495,7 +495,7 @@ sub test_expires_conditionally : Test(8) {
);
}
-sub test_expires_variance : Test(9) {
+sub test_expires_variance : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -533,7 +533,7 @@ sub test_expires_variance : Test(9) {
}
}
-sub test_not_in_cache : Test(3) {
+sub test_not_in_cache : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -564,7 +564,7 @@ sub test_serialize : Tests {
{
package DummySerializer;
BEGIN {
- $DummySerializer::VERSION = '0.40';
+ $DummySerializer::VERSION = '0.41';
}
sub serialize { }
sub deserialize { }
@@ -632,7 +632,7 @@ sub test_serializers : Tests {
}
}
-sub test_namespaces : Test(12) {
+sub test_namespaces : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -690,7 +690,7 @@ sub test_namespaces : Test(12) {
}
}
-sub test_persist : Test(1) {
+sub test_persist : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -705,7 +705,7 @@ sub test_persist : Test(1) {
'cache persisted between cache object creations' );
}
-sub test_multi : Test(8) {
+sub test_multi : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -753,7 +753,7 @@ sub test_multi : Test(8) {
cmp_set( [ $cache->get_keys ], [], "get_keys after remove_multi" );
}
-sub test_multi_no_keys : Test(4) {
+sub test_multi_no_keys : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -765,7 +765,7 @@ sub test_multi_no_keys : Test(4) {
lives_ok { $cache->remove_multi( [] ) } "remove_multi (no args)";
}
-sub test_l1_cache : Test(238) {
+sub test_l1_cache : Tests {
my $self = shift;
my @keys = map { "key$_" } ( 0 .. 2 );
my @values = map { "value$_" } ( 0 .. 2 );
@@ -775,7 +775,7 @@ sub test_l1_cache : Test(238) {
my $test_l1_cache = sub {
- is( $l1_cache->subcache_type, "l1_cache" );
+ is( $l1_cache->subcache_type, "l1_cache", "subcache_type = l1_cache" );
# Get on cache should populate l1 cache
#
@@ -831,8 +831,8 @@ sub test_l1_cache : Test(238) {
$cache =
$self->new_cache( l1_cache => { driver => 'Memory', datastore => {} } );
$l1_cache = $cache->l1_cache;
- isa_ok( $cache, $self->testing_driver_class );
- isa_ok( $l1_cache, 'CHI::Driver::Memory' );
+ isa_ok( $cache, $self->testing_driver_class, 'cache' );
+ isa_ok( $l1_cache, 'CHI::Driver::Memory', 'l1_cache' );
$test_l1_cache->();
# and in l1 position
@@ -843,12 +843,12 @@ sub test_l1_cache : Test(238) {
l1_cache => { $self->new_cache_options() }
);
$l1_cache = $cache->l1_cache;
- isa_ok( $cache, 'CHI::Driver::Memory' );
- isa_ok( $l1_cache, $self->testing_driver_class );
+ isa_ok( $cache, 'CHI::Driver::Memory', 'cache' );
+ isa_ok( $l1_cache, $self->testing_driver_class, 'l1_cache' );
$test_l1_cache->();
}
-sub test_mirror_cache : Test(216) {
+sub test_mirror_cache : Tests {
my $self = shift;
my ( $cache, $mirror_cache );
my ( $key, $value, $key2, $value2 ) = $self->kvpair(2);
@@ -901,7 +901,7 @@ sub test_mirror_cache : Test(216) {
$test_mirror_cache->();
}
-sub test_subcache_overridable_params : Tests(5) {
+sub test_subcache_overridable_params : Tests {
my ($self) = @_;
my $cache;
@@ -1156,7 +1156,7 @@ sub test_clear : Tests {
}
}
-sub test_logging : Test(12) {
+sub test_logging : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -1203,7 +1203,7 @@ sub test_logging : Test(12) {
$log->empty_ok();
}
-sub test_stats : Test(5) {
+sub test_stats : Tests {
my $self = shift;
my $stats = $self->testing_chi_root_class->stats;
@@ -1283,7 +1283,7 @@ sub test_stats : Test(5) {
);
}
-sub test_cache_object : Test(6) {
+sub test_cache_object : Tests {
my $self = shift;
my $cache = $self->{cache};
my ( $key, $value ) = $self->kvpair();
@@ -1310,7 +1310,7 @@ sub test_cache_object : Test(6) {
);
}
-sub test_size_awareness : Test(12) {
+sub test_size_awareness : Tests {
my $self = shift;
my ( $key, $value ) = $self->kvpair();
@@ -1344,7 +1344,7 @@ sub test_size_awareness : Test(12) {
$time, "set options respected by size aware cache" );
}
-sub test_max_size : Test(22) {
+sub test_max_size : Tests {
my $self = shift;
is( $self->new_cache( max_size => '30k' )->max_size,
@@ -1366,7 +1366,7 @@ sub test_max_size : Test(22) {
}
}
-sub test_max_size_with_l1_cache : Test(44) {
+sub test_max_size_with_l1_cache : Tests {
my $self = shift;
my $cache = $self->new_cleared_cache(
@@ -1409,7 +1409,7 @@ sub test_max_size_with_l1_cache : Test(44) {
}
}
-sub test_custom_discard_policy : Test(10) {
+sub test_custom_discard_policy : Tests {
my $self = shift;
my $value_20 = 'x' x 6;
my $highest_first = sub {
@@ -1438,7 +1438,7 @@ sub test_custom_discard_policy : Test(10) {
}
}
-sub test_discard_timeout : Test(4) {
+sub test_discard_timeout : Tests {
my $self = shift;
my $bad_policy = sub {
return sub { '1' };
@@ -1463,7 +1463,7 @@ sub test_discard_timeout : Test(4) {
);
}
-sub test_size_awareness_with_subcaches : Test(19) {
+sub test_size_awareness_with_subcaches : Tests {
my $self = shift;
my ( $cache, $l1_cache );
@@ -1541,7 +1541,7 @@ sub is_about {
}
}
-sub test_busy_lock : Test(5) {
+sub test_busy_lock : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -1568,7 +1568,7 @@ sub test_busy_lock : Test(5) {
is( $cache->get( $key, @bl ), $value, "hit after busy lock" );
}
-sub test_obj_ref : Tests(8) {
+sub test_obj_ref : Tests {
my $self = shift;
# Make sure obj_ref works in conjunction with subcaches too
@@ -1593,7 +1593,7 @@ sub test_obj_ref : Tests(8) {
$validate_obj->();
}
-sub test_metacache : Tests(3) {
+sub test_metacache : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -1603,7 +1603,7 @@ sub test_metacache : Tests(3) {
is( $cache->metacache->get('foo'), 5 );
}
-sub test_scalar_return_values : Tests(5) {
+sub test_scalar_return_values : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -1621,7 +1621,7 @@ sub test_scalar_return_values : Tests(5) {
$check->( sub { $cache->get('a') } );
}
-sub test_no_leak : Tests(2) {
+sub test_no_leak : Tests {
my ($self) = @_;
my $weakref;
@@ -1637,7 +1637,7 @@ sub test_no_leak : Tests(2) {
Class::MOP::Class->create( 'My::CHI' => ( superclasses => ['CHI'] ) );
-sub test_driver_properties : Tests(2) {
+sub test_driver_properties : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -1646,7 +1646,7 @@ sub test_driver_properties : Tests(2) {
is( $cache2->chi_root_class, 'My::CHI', 'chi_root_class=My::CHI' );
}
-sub test_missing_params : Tests(13) {
+sub test_missing_params : Tests {
my $self = shift;
my $cache = $self->{cache};
@@ -1,6 +1,6 @@
package CHI::t::GetError;
BEGIN {
- $CHI::t::GetError::VERSION = '0.40';
+ $CHI::t::GetError::VERSION = '0.41';
}
use strict;
use warnings;
@@ -18,7 +18,7 @@ sub writeonly_cache {
);
}
-sub test_get_errors : Test(10) {
+sub test_get_errors : Tests {
my ( $key, $value ) = ( 'medium', 'medium' );
my $error_pattern =
@@ -1,6 +1,6 @@
package CHI::t::Initialize;
BEGIN {
- $CHI::t::Initialize::VERSION = '0.40';
+ $CHI::t::Initialize::VERSION = '0.41';
}
use strict;
use warnings;
@@ -27,7 +27,7 @@ sub is_bad {
sprintf( "died with params '%s'", dump_one_line( \@params ) ) );
}
-sub test_driver_options : Test(7) {
+sub test_driver_options : Tests {
my $cache;
is_good( driver => 'Memory', global => 1 );
is_good( driver => 'File' );
@@ -1,13 +1,13 @@
package CHI::t::Null;
BEGIN {
- $CHI::t::Null::VERSION = '0.40';
+ $CHI::t::Null::VERSION = '0.41';
}
use strict;
use warnings;
use CHI::Test;
use base qw(CHI::Test::Class);
-sub test_basic : Test(3) {
+sub test_basic : Tests {
my ( $key, $value ) = ( 'medium', 'medium' );
my $cache = CHI->new( driver => 'Null' );
$cache->set( $key, $value );
@@ -1,6 +1,6 @@
package CHI::t::RequiredModules;
BEGIN {
- $CHI::t::RequiredModules::VERSION = '0.40';
+ $CHI::t::RequiredModules::VERSION = '0.41';
}
use strict;
use warnings;
@@ -9,7 +9,7 @@ use base qw(CHI::Test::Class);
sub required_modules { return { 'Data::Dumper' => undef, 'blarg' => undef } }
-sub test_blarg : Test(1) {
+sub test_blarg : Tests {
require Blarg;
Blarg->funny();
}
@@ -1,13 +1,13 @@
package CHI::t::Sanity;
BEGIN {
- $CHI::t::Sanity::VERSION = '0.40';
+ $CHI::t::Sanity::VERSION = '0.41';
}
use strict;
use warnings;
use CHI::Test;
use base qw(CHI::Test::Class);
-sub test_ok : Test(1) {
+sub test_ok : Tests {
ok( 1, '1 is ok' );
}
@@ -1,6 +1,6 @@
package CHI::t::SetError;
BEGIN {
- $CHI::t::SetError::VERSION = '0.40';
+ $CHI::t::SetError::VERSION = '0.41';
}
use strict;
use warnings;
@@ -18,7 +18,7 @@ sub readonly_cache {
);
}
-sub test_set_errors : Test(14) {
+sub test_set_errors : Tests {
my ( $key, $value ) = ( 'medium', 'medium' );
my $error_pattern =
@@ -1,6 +1,6 @@
package CHI::t::Subcache;
BEGIN {
- $CHI::t::Subcache::VERSION = '0.40';
+ $CHI::t::Subcache::VERSION = '0.41';
}
use CHI::Test;
use CHI::Util qw(can_load);
@@ -8,7 +8,7 @@ use base qw(CHI::Test::Class);
use strict;
use warnings;
-sub test_option_inheritance : Tests(8) {
+sub test_option_inheritance : Tests {
my $self = shift;
return 'Data::Serializer not installed'
@@ -34,7 +34,7 @@ sub test_option_inheritance : Tests(8) {
is( $cache->l1_cache->depth, 2, 'l1 cache depth' );
}
-sub test_bad_subcache_option : Tests(1) {
+sub test_bad_subcache_option : Tests {
my $self = shift;
throws_ok(
sub {
@@ -1,6 +1,6 @@
package CHI::t::Subclass;
BEGIN {
- $CHI::t::Subclass::VERSION = '0.40';
+ $CHI::t::Subclass::VERSION = '0.41';
}
use strict;
use warnings;
@@ -12,7 +12,7 @@ use base qw(CHI::Test::Class);
{
package CHI::t::Subclass::Driver::HasUnsupported;
BEGIN {
- $CHI::t::Subclass::Driver::HasUnsupported::VERSION = '0.40';
+ $CHI::t::Subclass::Driver::HasUnsupported::VERSION = '0.41';
}
use Moose;
extends 'CHI::Driver::Memory';
@@ -20,7 +20,7 @@ BEGIN {
__PACKAGE__->meta->make_immutable;
}
-sub test_unsupported : Tests(2) {
+sub test_unsupported : Tests {
my $cache = CHI->new(
driver_class => 'CHI::t::Subclass::Driver::HasUnsupported',
global => 1
@@ -1,6 +1,6 @@
package CHI::t::Util;
BEGIN {
- $CHI::t::Util::VERSION = '0.40';
+ $CHI::t::Util::VERSION = '0.41';
}
use strict;
use warnings;
@@ -11,12 +11,12 @@ use List::MoreUtils qw(uniq);
use base qw(CHI::Test::Class);
# The inevitably lame unique_id test
-sub test_unique_id : Tests(1) {
+sub test_unique_id : Tests {
my @ids = map { unique_id } ( 0 .. 9 );
cmp_deeply( \@ids, [ uniq(@ids) ], 'generated ten unique ids' );
}
-sub test_random_string : Tests(2) {
+sub test_random_string : Tests {
my @strings = map { random_string(100) } ( 0 .. 2 );
cmp_deeply(
\@strings,
@@ -30,14 +30,14 @@ sub test_random_string : Tests(2) {
);
}
-sub test_non_common_constructor_params : Tests(1) {
+sub test_non_common_constructor_params : Tests {
my $params =
{ map { ( $_, 1 ) } qw( foo expires_in bar baz on_get_error ) };
my $non_common_params = CHI::Driver->non_common_constructor_params($params);
cmp_deeply( $non_common_params, { map { ( $_, 1 ) } qw(foo bar baz) } );
}
-sub test_parse_memory_size : Tests(5) {
+sub test_parse_memory_size : Tests {
my %results = (
'12345' => '12345',
'50K' => 50 * 1024,
@@ -1,6 +1,6 @@
package CHI;
BEGIN {
- $CHI::VERSION = '0.40';
+ $CHI::VERSION = '0.41';
}
use 5.006;
use Carp;
@@ -93,7 +93,7 @@ CHI - Unified cache handling interface
=head1 VERSION
-version 0.40
+version 0.41
=head1 SYNOPSIS
@@ -102,6 +102,7 @@ version 0.40
# Choose a standard driver
#
my $cache = CHI->new( driver => 'Memory', global => 1 );
+ my $cache = CHI->new( driver => 'RawMemory', global => 1 );
my $cache = CHI->new( driver => 'File',
root_dir => '/path/to/root'
);
@@ -109,7 +110,7 @@ version 0.40
root_dir => '/path/to/root',
cache_size => '1k'
);
- my $cache = CHI->new( driver => 'Memcached',
+ my $cache = CHI->new( driver => 'Memcached::libmemcached',
servers => [ "10.0.0.15:11211", "10.0.0.15:11212" ],
l1_cache => { driver => 'FastMmap', root_dir => '/path/to/root' }
);
@@ -122,15 +123,18 @@ version 0.40
# Create your own driver
#
- my $cache = CHI->new( driver_class => 'My::Special::Driver' );
+ my $cache = CHI->new( driver_class => 'My::Special::Driver', ... );
- # Basic cache operations
+ # Cache operations
#
my $customer = $cache->get($name);
if ( !defined $customer ) {
$customer = get_customer_from_db($name);
$cache->set( $name, $customer, "10 minutes" );
}
+ my $customer2 = $cache->compute($name2, "10 minutes", sub {
+ get_customer_from_db($name2)
+ });
$cache->remove($name);
=head1 DESCRIPTION
@@ -458,8 +462,8 @@ background just before it actually expires, so that users are not impacted by
recompute time.
Note: Prior to version 0.40, the last two arguments were in reverse order; both
-will be accepted for backward compatibility. We think the code looks better at
-the end.
+will be accepted for backward compatibility. We think the coderef looks better
+at the end.
=back
@@ -943,6 +947,11 @@ L<CHI::Driver::Memory|CHI::Driver::Memory> - In-process memory based cache
=item *
+L<CHI::Driver::RawMemory|CHI::Driver::RawMemory> - In-process memory based
+cache that stores references directly instead of deep-copying
+
+=item *
+
L<CHI::Driver::File|CHI::Driver::File> - File-based cache using one file per
entry in a multi-level directory structure
@@ -981,6 +990,10 @@ L<CHI::Driver::DBI|CHI::Driver::DBI> - Cache in any DBI-supported database
L<CHI::Driver::BerkeleyDB|CHI::Driver::BerkeleyDB> - Cache in BerkeleyDB files
+=item *
+
+L<CHI::Driver::Redis|CHI::Driver::Redis> - Cache in L<Redis|http://redis.io/>
+
=back
This list is likely incomplete. A complete set of drivers can be found on CPAN
@@ -988,6 +1001,14 @@ by searching for "CHI::Driver".
=for readme stop
+=head1 PERFORMANCE COMPARISON OF DRIVERS
+
+See L<CHI::Benchmarks> for a comparison of read/write times of both CHI and
+non-CHI cache implementations.
+
+C<etc/bench/bench.pl> in the C<CHI> distribution contains a script to run these
+types of benchmarks on your own system.
+
=head1 DEVELOPING NEW DRIVERS
See L<CHI::Driver::Development|CHI::Driver::Development> for information on
@@ -0,0 +1,3 @@
+#!perl -w
+use CHI::t::Driver::RawMemory;
+CHI::t::Driver::RawMemory->runtests;